Swagger

Swagger is an ideal way of documenting standard APIs. Swagger is helpful when we deploy APIs in Azure. Swagger is primarily used for documenting API. The question is, why document APIs? Constructing APIs that are internal in the enterprise or for public consumption, the theme is similar to that the developers usually use in the apps that they are building. For other developers to be able to use our API, the API must be properly documented, otherwise how would we know what are the endpoints exposed by the API and what are the operations that are supported on those endpoints.

History of Swagger

• Swagger was the specification for how to create an API definition file.
• When the new version was released, Swagger 2.0 specification became the open API specification (OAS).
• The swagger is no longer a specification but it is a collection of tools that use the open API specification.
• Huge people refer to OAS as swagger, but technically it is not.

Swagger will provide an editor for the open API specification files. To visit the swagger editor website, go to the following link.

https://swagger.io/tools/swagger-editor

Swagger is the most popular tool used for generating interactive documentation. The API users can understand it effortlessly because it generates an interactive API for the users.

Distinguish between the swagger and open API specification are:

The openAPI is particularly specified whereas the swagger is a tool used for implementing the specification. The development of the OpenAPI specification is done by the OpenAPI initiative that includes more than 30 organizations from many areas of the world. Smartbear software is the company that developed the swagger tool and is also a member of the openAPI initiative, so also helped in developing the specification.

We have swagger tools

1. Swagger Editor-This tool that will allow us to edit the open API specifications in YAML inside the browser and can also preview the documentation in real time.
2. Swagger UI-This tool which is a collection of HTML, javascript and CSS assets that allows us to generate beautiful documentation dynamically.
3. Swagger codegen- API client libraries, server stubs and documentation can be automatically generated.
4. Swagger core- It consists of java related libraries which are used for creating, consuming and working with the API definitions.
5. Swagger Inspector- It is considering an API testing tool that allows us to validate our APIs and generate OpenAPI definitions from an existing API.

Documentation in Swagger:

What is auto generated documentation?

Swagger tools takes the OAS files and generates the HTML documentation from it so that it can be updated on the web. As long as the OAS file keeps up to the date then the documentation is likely to be more accurate rather than writing the documentation manually. It also allows us to try out the requests from within the documentation so that it can help the developer implement the code.

How to set up swagger UI?

1. We have to select the Swagger UI Github project. Click the Download zip button. Download the files to a desired location on your computer and extract the files. The only folder we will be working with here is the dist folder. Everything else is used only if we are regenerating the files, which is beyond the scope of this tutorial.
2. dist folder should be dragged out of the swagger-ui-master folder. Then delete

The swagger-ui-master folder.

3. open index.html in a text editor in the dist folder.
4. Look  for the following code

url = “http://petstore.swagger.io/v2/swagger.json”;

1. change the url value from

http://petstore.swagger.io/v2/swagger.json to the following: “swagger.yaml”;.

2. Drag the swagger.yaml file  that we can create earlier into the same directory as the index.html file we just edited.
3. Save the file.
4. To view the file, open it in Firefox.

Questions

1. What is swagger?
2. How does Swagger work?