- Swagger is an open source API documentation framework.
- Swagger is used for documenting the rest. API’s or end points.
- It provides HTML view of the API documentation With JSON Support and detailed information on the Http methods.
- Rest API are basically designed to be used in some kind of application.
- The API’s developed by backend developers should be delivered to front end developers in a way that they can understand and test those with proper parameters before integration.
- Documentation provides following information
- End point URL’s
- Method used in URL
- Data to be passed
- Mandatory and optional parameters
- Authentication information of URL.
- We use swagger UI to visualise documentation.
- Swagger is a set of rules or a specification For a format describing rest API’s
- API’s are Developed by backend developers, and integrated by front and developers.
- API are contracts between UI and backend teams.
- It provides an easy way to share API documentation among developers,product managers, QA, and other stakeholders.
- Use Swagger editor
- We create documentation using two ways.
- First is editor online i.e editor.swagger.io
- We write YML code, which is automatically converted to HTML.
- We can clone the swagger editor.
- We then downloaded Jason file of the document in yaml
- This can be done using a Gulp task or maven task or Supported code management software to generate Json file.
- Download swagger UI distribution
- Import Json file in distribution
- Upload it to your website.
- Swagger organisation
- Swagger organises resources under following categories
- Resource
- A resource is a collection of end points in one category.
- A resource represents a controller.
- Endpoint
- It is simply a unique URL that represents an object or collection of objects.
- Model
- A description of a resource and its response.
- Model defines the contract between backend and frontend developers.
- Swagger drives its specification from open API structure.
- Different keys used in YML are
- Schemas
- Define the HTTP and HTTPS nature of resource
- Array of Protocols
- Paths
- We can define end points in the Path property
- For each end point, we define following properties
- GET/Post/Put/Delete
- Method of endpoint
- Summary
- Description
- Operation ID
- Consumes
- Type of response it consumes
- Produces
- Type of response it produces
- Parameter
- Parameters to be sent with a request
- It is an array
- Response
- Response at various HHTP status like 200, 405, et cetera.
- SECURITY
- Authorisation required for that API, for example, any specific group of users that can access et cetera.
- We can get all above syntax at swagger open API specification.
- Install and setup Swagger Locally
- Clone Swagger editor from github and run it on any server like apache.
- To configure spring boot with swagger Add the dependencies as follows
- https://github.com/gauravmatta/springmvc/tree/master/complaint-manager
- Create a bean of Docket class
- Docket is an object of swagger, which contains all information about our application that we want to configure.
- To setup we can find help on https://springdoc.org/
- springdoc-openapiv1 is only supported till Spring Boot 2.0.
- @Hidden is used to hide API’s in controller.
- Common configuration can be found at
- Controller based configuarion
- Swagger is added to Rest API’s to generate its API documentation.
- Spring Fox used for swagger does not support spring boot 3.
- For spring boot3 Use spring doc OpenAPI.
- When migrating from Spring 2.x to Spring 3.x use following documentation to migrate from Spring Fox Swagger to Spring Doc open api.
- https://springdoc.org/migrating-from-springfox.html
Swagger
Subscribe to:
Posts (Atom)
No comments:
Post a Comment