OpenAPI design-first API reference

Question

I am trying to document a REST API reference using the OpenAPI format (v2). I want it to be "design-first", meaning that my swagger spec will be the contract of the API implementation.

I have tried many modules and solutions e.g. swagger-node (too opiniated about folder structure and implementation), swaggerize-express which forces me to use express, etc. I also tried an generator-openapi-repo but it seems outdated and no more maintained.

Any solution out there to document a REST API reference, design-first and without coupling the documentation with the actual implementation?

Answer 1

You can use swagger-node just as a local editor. With these commands, run the swagger editor and write your swagger specification:

npm install -g swagger

swagger project create my-app

swagger project edit

After finishing the design, swagger.yaml file which is stored in api/swagger/, can be used for any implementation.

If you're searching for an online editor, checking these tools might be helpful.

• Simple editor: editor.swagger.io
• Collaborate editor (offering free & paid version): swaggerhub.com