Swagger is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability.
Swagger was created to help fulfill the promise of APIs and is 100% open source software.
The Swagger specification defines a set of files required to describe an API. These files can then be used by the Swagger-UI project to display the API and Swagger-codegen to generate clients or servers in various languages. Additional utilities can also take advantage of the resulting files, such as testing tools.
If you only have one API to be built, you can save your specification anywhere and you don’t need any external references; however, you might work for an organization which is building hundreds or thousands APIs and there are so many shared references between APIs like common headers, error status etc. In this case, it is recommended to create a separate repo for specification only. Normally, it will be called swagger.
Within this folder, each api will have its own sub folder and common shared references will be in the root folder.
Swagger spec. can be edited in yaml or json format but most people will be using yaml format and we are stick to it.
Using the online editor
To access the Swagger online editor, click the following link.
To import an existing specification from the File –> Import File …
To save/export the specification in YAML format - File –> Download YAML.
Online editors work if you are working on only one API without any externalized references. If you want to work with multiple APIs, you have to run the editor locally.
Running editor locally
git clone https://github.com/swagger-api/swagger-editor.git
Now your default browser will be started and point to 127.0.0.1:8080/# with a sample specification loaded.
Create a new specification
The swagger-editor serves the static files via an HTTP server. To work on API specifications, the simplest way is to clone the swagger repository directly in the Swagger editor folder.
git clone https://github.com/networknt/swagger.git
When saving/exporting your specification, please use swagger.yaml filename in your API sub folder under swagger.
Common object specifications are located in the root folder of the /swagger repository. Ex. header.yaml,
error.yaml, etc. To refer these common specification files in API specification
In the Github networknt organization, we have a repo model-config that contains specifications and light-codegen configurations with README.md to generate projects. You can find OpenAPI specifications in the rest folder.
Usually, we are using the online swagger editor to create/update OpenAPI 3.0 specifications and then export to both YAML and JSON format to save them into the model-config repo.