Forum Discussion

tkeidar's avatar
tkeidar
Visitor
3 years ago

automatically ensure openapi.json matches my Express API endpoints

Hello,

 

I have an API server written in Typescript with Express and I'm currently writing the openapi.json V3 file with all the documentation.

1. Is there a better way to generate the openapi.json file automatically?

2. Is there a way to run some kind of script to validate that the current openapi.json file matches my codebase? I'd like to run it on my CI/CD process to ensure the documentation is always up to date.

 

Thanks!

2 Replies

  • tkeidar,

     

    1. There are several different ways to generate OpenAPI documents based off of existing code/APIs. One option is to generate a document based off your code. These usually come in the form of annotations or something that integrates with your framework. I found one specifically for Typescript here: https://tsoa-community.github.io/docs/introduction.html 

     

    You can also use the Swagger Inspector tool. This tool will allow you to make API calls to your services, and record both the request as well as the response. Once you've got a few request and responses recorded, you can generate a simple OpenAPI file. This won't be a complete solution as there may be a lot of details missing, but at least it will give you a strong jumping off point: https://inspector.swagger.io/builder 

     

    2. I've looked into this a little bit and I came across this website a while back: https://openapi.tools/. I think what you would want to take a look at is the Data Validator tools on this site. I haven't tested out any personally.

     

    Hope this helps!

    • johnjennifer's avatar
      johnjennifer
      Occasional Visitor

      express-openapi-validator is an unopinionated library that integrates with new and existing API applications. express-openapi-validator lets you write code the way you want; it does not impose any coding convention or project layout. Simply, install the validator onto your express app, point it to your OpenAPI 3 specification, then define and implement routes the way you prefer.