Swagger provides an editor for the Open API Specification files. To visit the swagger editor website, go to the following link:
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.
Difference between the Swagger and Open API specification
The OpenAPI is a specification whereas the Swagger is a tool used for implementing the specification. The development of the OpenAPI specification is done by the OpenAPI initiative that involves more than 30 organizations from the different areas of the world. Smartbear software is the company that developed the Swagger tool is also a member of the OpenAPI initiative, so it also helped in developing the specification.
Swagger is a tool associated with widely used tools for implementing the OpenAPI specification. The swagger toolset includes open source, free and commercial tools used at the different stages of the API lifecycle.
The following are the tools included in the Swagger:
- Swagger Editor: It is a tool that allows us to edit the Open API specifications in YAML inside the browser and can also preview the documentation is real time.
- Swagger UI: It is a tool which is a collection of HTML, Javascript, and CSS assets that allows us to generate the beautiful documentation dynamically.
- Swagger Codegen: It allows us to generate the API client libraries, server stubs, and documentation automatically.
- Swagger core: It consists of java related libraries which are used for creating, consuming and working with API definitions.
- Swagger Inspector: It is an API testing tool that allows you to validate your APIs and generate OpenAPI definitions from an existing API.
Documentation in Swagger
What is Auto-generated 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.
We will design and document the Restful API using Swagger editor.
Suppose we have a Student API and resource from which we will get the students name based on the Query parameter.
In Query parameter, we will pass the student name. In this API, we will also have the POST operation that adds new student with the help of this API.
We will also perform the GET operation that retrieves the data with the help of path parameter.
Open the Swagger editor in the browser as shown as below:
It is a very intelligent tool as it provides a bunch of suggestions. When we press ctrl+space, it provides you lots of suggestions.
First, we use openapi having version 3.0.0 shown as below:
Now we will add the basic information of our API in the metadata as shown as below:
Swagger tutorial 2
In the above, we have added the basic information such as the title of the API, description of the API and contact of the API.
The next we have to add the servers. We can add the multiple servers by adding the url of each server.
Swagger tutorial 3
Swagger tutorial 4
In the above, we have added the Student resource along with its description. Then, we have included the get operation.
GET :-
First, we provided the description of the get method and then we include the parameters that we are going to pass in the Get method.
We have passed query-based parameter named as Studentname and the next parameter is required which will be true as studentname parameter is mandatory in the Get method.
Now we will represent the schema of the query-based parameter. Inside the schema, we have included the type of the parameter and the example. In this case, we have specified the Query parameter.
Now we will specify the response that should be the next level.
We will first mention the responses: and then inside the responses, we need to specify the http code for which we are showing the responses. In the real scenario, we should cover all the major response codes.
Here, we will specify the happy scenario, i.e., 200 code representing a successful response. After the response code, we will specify the description of the response code, 'Successful response'.
Then, we will specify the format of the content, i.e., 'application/json' means that the content will be represented in the json format.
Once the format of the content is included, we need to specify the schema. Since this is the response, so get operation will be performed. The type of the operation is array and the array has a list of items so we will specify the items as a key.
The items has the properties key. As we can observe in the above screenshot that it contains three properties, i.e., Student id of type integer, Student name of type string and Studentremarks of type string.
POST :-
The next operation is the POST operation that we have to perform. First, we will specify the post method in the editor and then we add the description of the POST method 'Add a new Student'.
Inside the POST method, we need to specify the requestBody as it is expecting the requestBody in the JSON format in the student object.
In the content, we add the format of the content, i.e., 'application/json.' Since it is a POST operation, so we are expecting to have object type rather than an array type.
All the properties in the POST operation would be same as the GET operation. After adding all the properties, we will add the responses key in which we add the 201 code that represents the happy scenario. Under the responses key, we add the description of the response code, i.e., 'Record successfully added'.
Till now, we are getting the student resource with a query parameter. Suppose we want to get the student resource with a path parameter then we need to add the following code in the path:
description: Retrieve the Student based on a Path Parameter
get:
parameters:
-in: path
name: id
required: true
schema:
type: integer
responses:
200:
description: Success response with a path parameter
content:
application/json
Below file is the complete API definition file:
openapi: 3.0.0
info:
title: Student API
description: Student API by javahubpoint.com
contact:
name: javahubpoint
url: http://javahubpoint.com
version: 1.0.0
server:
-url: http://devapi.com
paths:
/student:
description: Student Resource
get:
description: Operation to fetch the Student data
parameters:
- in: query
name: studentname
required: true
schema:
type: string
example: John
responses:
200:
description: Successful Response
content:
application/json:
schema:
type: array
items:
properties:
Student ID:
type: integer
example: 1
Student Name:
type: string
example: Peter
Student Remarks:
type: string
example: High Grade Student
post:
description: Add a new Student
requestBody:
content:
application/json:
schema:
type: object
properties:
Student ID:
type: integer
example: 1
Student Name:
type: string
example: Peter
Student Remarks:
type: string
example: High Grade Student
responses:
201:
description: Record successfully added
/student{id}:
description: Retrieve the Student based on a Path Parameter
get:
parameters:
- in: path
name: id
required: true
schema:
type: integer
responses:
200:
description: Success response with a path parameter
content:
application/json:
schema:
type: array
items:
properties:
Student ID:
type: integer
example: 1
Student Name:
type: string
example: Peter
Student Remarks:
type: string
example: High Grade Student
Output :-
swagger tutorial 7
The above screenshots show that the API perform three operations.
-The first operation is the GET operation accepting the student name,
-the second operation is the POST operation accepting the requestBody in the JSON format and
-the third operation is the GET operation accepting the path parameter named as 'id'.