I'm working on a restAPI using Express.js and I'm wondering if there is a way for me to generate API documents that allow a user to view API definitions or possibly even try out the API call?
What you are looking for is a good JavaScript documentation generator. I found a decent one here http://apidocjs.com/example/.
This will allow you to use just Express as OP asked.
Swagger isn't for generating docs, it's for making APIs. So you are going to need to learn a full system to get that feature.
I found a couple more here that I haven't fully looked into yet which seem promising:
Docco here JSDoc here and an article on Documentor for Node
Swagger is an amazing project for auto generating API documentation. It includes an Express module.
http://swagger.io/
https://github.com/wordnik/swagger-node-express
I found this library to be very useful when it comes to keeping your documentation and route declaration logic close together:
https://www.npmjs.com/package/swagger-jsdoc
If you use Postman while developing you might already have a Postman collection containing the most relevant calls.
If that is the case Postman has a docs feature https://learning.postman.com/docs/publishing-your-api/documenting-your-api/
Related
Case: Google Chat support in node.js using the googleapis library.
I studied the documentation, created a service account and implemented authentication. In first step I used the chat.spaces.list() method and it worked (no error returned).
I want to send a message via chat, so I wanted to create a new space, I found the chat.spaces.create method (https://developers.google.com/chat/api/reference/rest/v1/spaces/create) Unfortunately, this method is not present in "googleapis" for node.js In general, I see that the list of methods in "googleapis" is different than the one in the documentation. Only spaces in the documentation, but spaces and rooms in the library... I'm lost. How to do it? Any tips?
I see that the list of methods in "googleapis" is different than the one in the documentation
I think you are seeing wrong documentation. Your reference link is REST API documentation. The nodejs googleapis client documentation you can see on https://googleapis.dev/nodejs/googleapis/latest/chat/classes/Resource$Spaces.html.
And also based on the REST API documentation, the API that you looking for(create space) is not general available.
† Supports user authentication in Developer Preview. App authentication isn't available.
You need to join Google Workspace Developer Preview Program to access that feature.
I'm trying to understand how to add i18n support to loopback which is built on top of express.js.
I've installed i18n-node and have read the express.js documentation. It looks like I don't want a global state of localization because I'll be serving HTTP responses. The i18n-node documentation recommends I attach it to the request object and gives an example.
My problem is that I can't find where/how to add this code into loopback. Everywhere I try to put the app.configuration function it says that method is undefined.
I have a feeling this is a middleware addition that I want to add to the middleware.json file in the routes phase. But I don't know how to do that.
Does anybody know a good way to internationalise a loopback app (server response messages, emails going out etc.)?
As per the documentation on their Github Page. I think the configuration code is best to keep in server/boot/ folder. As these are loaded as the server start and then, can be used by other rest endpoints. Don't forget to add JSON files for translations.
I don't think there are any other requirements as LoopBack is built on top of Express and most of their codes work same.
I inherited an existing API and I would like to document it with swagger, but I don't yet know the full scope of it. Can Swagger (or another middleware/tool) auto-magically generate the yaml (for swagger) based on the existing express routes?
For what I saw on other questions, it would appear that this is mostly a manual job, but I'm double-checking if someone here found a way around this.
I have experience in BOTH auto-generating the Swagger json and manually writing it out for an API that I helped build. Here are the pros/cons of both based on my experience.
Swagger AUTOMATIC Documentation Generation:
We used the swagger-node-express module in combination with swagger-ui.
https://www.npmjs.com/package/swagger-node-express
https://github.com/swagger-api/swagger-ui
Pros
Super easy to document. Just throw a few lines above the resource definition and the documentation (json) is automatically generated by the module.
Cons
You are no longer using straight up Express when you use this package. Your route definitions have to be defined through the Swagger module and this pulls you away from vanilla Express.
Swagger MANUAL Documentation Generation:
We just pulled swagger-ui into the project and wrote the documentation manually.
https://github.com/swagger-api/swagger-ui
Pros
This approach decouples the documentation from the Express framework. Express endpoints are written as they normally would be written and the Swagger documentation is defined separate from the Express framework. Allows you to write pure express.
Cons
Documentation changes become a little more tedious due to the fact that you are manually writing and changing the yaml or json yourself. It's a little bit harder than just updating a few lines of code above a resource. This approach is also a little more prone to documentation typos and errors due to the fact it is entirely manually typed.
If you are planning to manually write your swagger documentation use the swagger editor below to validate your manual docs.
http://editor.swagger.io/#/
Conclusion
For this API project, we started out by auto-generating the documentation using the swagger-node-express package. However, we realized that decoupling the swagger documentation from the express library was important to enable us to use all the features and functionality of Express. I recommend manually writing the docs to have full control over both the Swagger documentation and the Express web framework that your app will use.
There is an option: you can embed middleware that will analyse all requests and responses and generate specification for you: https://github.com/mpashkovskiy/express-oas-generator
Then you can use it through your's app Swagger UI like http://host:port/api-docs
Yes !!!. You can use this awesome project typescript-test. Here is sample app. Clone it, run npm i,npm run swagger and go to /dist/swagger.json. Done. Swagger yaml and json is generated based on express routes !
With express-sitemap-html you may automatically generate a minimalistic Open API definition (only including route parameters) and install a Swagger UI for all routes of an existing express app. You only need:
const sitemap = require('express-sitemap-html')
...
sitemap.swagger('Your app name', app) // given that app is an express instance
Instead of analyzing HTTP requests at runtime, this approach inspects express app instance and mounted routes.
PROs you don't need to perform ahead requests to get an updated list of available routes.
CONs it provides untyped parameters features.
Have a look to swagger-jsdoc. It's a different approach.
The docs stick to the code, and also lets the express code to remain pure.
Guides:
https://dev.to/acanimal/express-api-with-autogenerated-openapi-doc-through-swagger-7na
https://dev.to/akshendra/generating-documentation-on-the-fly-in-express-2652
I have this Freebase query and need to use it in NodeJS + ExpressJS or NodeJS + Superagent. I tried Google API module and the Freebase module (that doesn't npm install!), but i'm very confuse about how to use. I dig into google and documentation without success. I already have my Google Freebase API Key and read in some web posts that always need to use it and in others that it's not necessary. I'm very confuse about it.
Thanks!
For future generations who google here like I did, the npm module is now working and appears to be awesome.
https://www.npmjs.org/package/freebase
I'm building my first node.js app, and trying to integrate it with the Instapaper API. Instapaper only uses XAuth, and I'm a little confused how it works.
Should I use the node-oauth module and try to customize it for xauth? Or should I roll my own xauth? Or something else, maybe?
I'd checkout something like EveryAuth, see how they are handling the various options out there, forking it, and then contributing back with a new implementation.
Good luck man.
Here is how to get it working with the oauth module.
https://stackoverflow.com/a/9645033/186101
You'd still need to handle storing the tokens for your users, but that answer should get you u and running for testing the API in node.