The prominent industry standard for designing and documenting HTTP APIs is called the OpenAPI standard. The SwaggerEditor is an open source application owned and maintained by SmartBear Software that allows software architects and developers to create, edit, and view specification documents and while developing the specification verify that they comply with the OpenAPI standard.
To use the SwaggerEditor you can start up a web server using the swagger-editor-dist npm module, use the OpenAPI (Swagger) Editor extension in VSC, or use other API tools that incorporate the SwaggerEditor like Insomnia. Below I provide instructions on using the swagger-editor-dist npm module.
Install and Run the SwaggerEditor
The SmartBear Software company provides multiple npm module that contain the SwaggerEditor. Below are instructions showing how to install and run SwaggerEditor contained in the swagger-editor-dist npm module.
To install the editor, first create a directory to hold the SwaggerEditor code. Then open VSC to the directory you created.
Open the VSC terminal and run the following command to install the swagger-editor-dist npm module
$ npm install swagger-editor-dist
Install the http-server module
$ npm install http-server
Start up the SwaggerEditor on the http server.
$ npx http-server node_modules/swagger-editor-dist
The SwaggerEditor is running in a web server on your computer. To use the editor open up a browser and navigate to localhost:8080. If successful you should be able to use the editor in the browser.
To start, clear the editor by pressing File > Clear editor.
Create a YAML Specification File For Your API Server
Write your API specification in YAML format so that it complies with the OpenAPI version 3.0 standard. Use the following reference docs.
- Example API Descriptions (e.g. petstore)
- OpenAPI Specification Explained
- Chapter 4, Specifications of the OpenAPI specifications
- My example
Your specification should use components to limit redundancy, should provide example input and output, and should reflect all response status codes that your API server sends.
Save Your YAML File Using the Web-based SwaggerEditor
If using the browser based SwaggerEditor, when you are finished writing your server’s specification, press File > Save as YAML. A .yaml file will be saved to your browser’s downloads.
Create a directory named specs in the root of your API server’s base directory, then copy the YAML file in your browser’s downloads to the specs directory. Next, rename the .yaml file to an appropriate name (e.g. user.yaml).
Push to GitHub
When finished, push your .yaml file to GitHub.