I'm working with a fairly complex NodeJS API that has been written using hapiJS.
The API uses the hapi-swagger npm module to generate the API documentation.
I'm now investigating how to integrate the Amazon API Gateway with this API, in order to provide the authentication/request throttling etc.
To create an Amazon Gateway API, it appears that I need to provide a Swagger definition.
My question is, how do I generate this swagger definition? I'm assuming there must be some way to do this automatically from hapi-swagger, but I haven't been able to find it.
If you are using hapi-swagger the default endpoint that returns the swagger.json is /swagger.json.
See https://github.com/glennjones/hapi-swagger/blob/c02dd0dc8632766006854d1a4ddcd88a77a411c8/optionsreference.md#json-json-endpoint-needed-to-create-ui --> jsonPath
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 would like to ask your help in relation with one issue i am facing. So basically i defined a swagger 2.0 spec for an API, and on the operation's responses i used the schema property in order to reference some definitions for objects that reflect the responses structure. I validated the spec on the Swagger Editor, and it is valid, and also if i generate the client code, using Swagger Codegen, the client app works well consuming the API. Now, the problem is. I went to the Developer Portal and on the API's details page, i checked the API definition (Open API option) and i compared the spec with my original spec that i used to import the API on the API Management service. And i noticed that the schema property is missing, so it is not referencing the schema of the response. Any idea?
Thanks
I figured out the issue. Apparently using the schema property on the responses, according to Swagger 2.0 spec, you can use nested $refs, in order to reference definitions inside each other. But apparently, it is not possible for Azure API Management Service, since it is mentioned as a limitation in the following link: API Management - API Import restrictions.
Anyway, i will try to change my API's spec in order to avoid nested $refs and workaround the issue.
Thanks
We are using aws gateway api with lambda functions to create our api.
We then decided that it would be a good idea to have it all documented with swagger, and use it to validate the requests in a similar fashion as it happens with express middleware frameworks.
However i cant find a way to pass a request object and validate it against a swagger spec manually without using one of these frameworks.
Now my question is:
How do validate a request against a swagger spec, by pointing the request at a specific path in spec, what frameworks could i use to achieve it?
I'm using swagger to define my API and API-gateway to host this API. I found the following lib (see here) to import my API definition to AWS and automatically create the API (models, end-points, etc). It's cool. But, it's not able to validate Requests based on models (defined in Swagger definition). It means that you can send a JSON payload without the required fields.
I don't want to write a node.JS code to check the format because it will not be much easy for schema updates. I'm wondering if it's possible to check if a JSON payload is compatible with a specific type of object defined in swagger (objects defined in the "definitions" section).
If it's possible, it will allow me to only update my swagger definition.
Thanks,
Romain.
We are tracking this feature request on our backlog. For clarity, this would be implemented in the API Gateway service, not the Swagger importer. In the meantime you will need to implement validation logic yourself. See here for libraries which may help: http://json-schema.org/implementations.html
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