I am looking for a way to generate OpenAPI/Swagger API definitions from code written in Node.JS/Express.JS/Typescript.
Ideally this would be just annotations the I had to my Express Typescript base controllers and this generate the OpenApI/Swagger by running some sort of command line, this way the API definition would always stay in sync with the actual implementation, and additionally this tool should generate some sort of middleware that can implement parameter validation of the controllers input parameters.
Thank you, kindly
Oscar
If you want swagger generated for you, you can make use of NestJs.
NestJs also provides inbuilt middle ware for validation.
If you wanna know more visit this link
Related
I'm a node/JS beginner, so really sorry if I missed something.
My Need is the following, I have a Swagger/OpenAPI3.0 yaml file describing an API that I need to consume. As the client will be an Node API gateway, I want this API Client code for Node.
I use the Swagger Editor to generate client like this :
Screenshot of Swagger Editor
But the generated code seems dedicated to browser client and I need to refactor this to have it works properly with node.
Does it exist an alternative?
Thanks a lot for your help.
One of the libraries which can create a TypeScript API client for Node.js at runtime from an OpenAPI v3 definition is called openapi-client-axios.
I have DTOs specified with Class-Validator and I am looking for a library that can be used to generate Swagger specification from it. I am not using it for a REST API, the code is addressing an IoT/MQTT scenario - I simply use Class-Validator to manage JSON.
NestJS/Swagger is the best maintained library. I would like to use it's capability to produce Swagger definitions without a NestJS Server. Ideally I would like to pass in a DTO definition and get it's Swagger schema.
I have been reading the source, but am struggling to understand which function in the framework actually does that. At best, I have been able to track it down to modelsDefinitions property in swagger-explorer class.
As best I can tell, from there, api-parameters.explorer and api-produces.explorer. The way they work is not clear to me. I was wondering of someone might help me out?
I'd like to add that I am aware of class-validator-jsonschema, but it is not maintained and no longer seems to work properly.
nestjs/swagger does not expose what you need as its public API which you cannot access it. The class you're looking for is SchemaObjectFactory and the method is exploreModelSchema.
Reference:
SwaggerObjectFactory
Test
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'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/