Reference: https://www.javatpoint.com/swagger
Swagger is the standard way of documenting the Standard APIs.
Swagger is one of the popular tools used for generating an interactive documentation. It generates an interactive API for the users so that they can understand about the API more quickly.
For the other developers to be able to use our API, the API must be properly documented; otherwise, how would they know that what are the endpoints exposed by the api and what are the operations supported on those endpoints? What parameters should they pass, and what will they get back? What authentication methods to use?. To answer these questions, it is very important to document the APIs; if you want APIs to be consumed and properly used.
Swagger and Open API specification are the ways to document an API specifying that what exactly APIs can do
There are several types of APIs, but the swagger specifically deals with the Web API.
JSON file is passed over the web, it is unlike YAML thus YAML is for configuration files that are not passed over the web.
Documentation in Swagger: What is Autogenerated documentation?
Tools such as Swagger takes the OAS files and generate the HTML documentation from it so that it can be updated on the web. As long as the OAS file is kept up to date then the documentation is likely to be more accurate rather than writing the documentation manually. It also allows you try out the requests from within the documentation so that it can help the developer for implementing the code.
Anatomy of a Request
There are five different parts to be found in the Http request:
- Method: The method describes the action to be performed. The methods could be POST, PUT, DELETE, GET.
- URL: It specifies the name on which the action is to be performed.
- Query parameters
- Headers: Headers are used to store the information about the request.
- Body: Body contains the additional data.
 |
| Scheme, Host, Base Path, Path |
Security
Here, Security means authentication and authorization. Authentication means to validate the user through their username and password. The authorization means allowing the user to access the data.
The security can be set in the following ways:
- None: Here, None means that no security is set to access the API.
- Basic Auth: It means that the username and password are set for each request.
- API Key: The key is set to access the API.
- OATH: It is an authorization scheme.
