Introduction to Swagger Documentation Format

In this section, we look at the generated documentation in detail. Swagger is a specification for documenting REST API. It specifies the format (URL, method, and representation) to describe REST web services. It also provides tools to generate/compute the documentation from the application code.

As an application developer, we write web services using a framework, Swagger scans application code, and exposes the documentation on URL. A client can consume this URL and learn how to use REST web services: which HTTP methods to call on which URL, which input documents to send, which status code to expect, etc.

We’re going to see what is inside the Swagger documentation. When we have a close look at the documentation of the web API, we see some important elements in the starting of the documentation, as shown in the following image.

There are following important swagger elements that are present in the Swagger documentation.

swagger: It specifies the version specification of Swagger, which we are using.
info: The info tab contains the information about API like description, version of API, the title of API, termOfServices, and URL.
host: It specifies the host where we are hosting the service.
basePath: It is used in URI after the port number and before the API.
tags: We can assign tags to our resources. It is used to group resources in multiple categories.
paths: It specifies the path of resources that we are exposing and the different operations that can be performed on these resources.
definitions: It includes the different elements that we have used in our API.

We will discuss three elements info, paths, and definitions in detail.

Let’s see what is inside the info element:

  “info”:{“description”:”Api Documentation”,”version”:”1.0″,”title”:”Api Documentation”,”termsOfService”:”urn:tos”,”contact”:{},”license”:{“name”:”Apache 2.0″,”url”:”http://www.apache.org/licenses/LICENSE-2.0″}},  

description: It contains the high level information of API.
version: It shows the version of API which we are exposing.
title: It specifies the title of API.
termOfService: It specifies the term of service, if any.
contact: It specifies the contact detail of a person, if any.
license: It specifies the default license Apache 2.0.

Let’s expand the path element. It contains all the path that we are exposing.

  paths: {  /error: {-}  /hello-world: {-}  /hello-world-bean: {-}  /hello-world-internationalized: {-}  /hello-world/path-variable/{name}: {-}  /users: {-}  /users/{id}: {-}  },  

The two most important resources are “/users” and “/users/{id}“. These resources exposes the group of users. Let’s expand these two resources one by one.

Expanding “/users” resource:

  “/users”:{“get”:{“tags”:[“user-resource”],”summary”:”retriveAllUsers”,”operationId”:”retriveAllUsersUsingGET”,”produces”:[“*/*”],”responses”:{“200”:{“description”:”OK”,”schema”:{“type”:”array”,”items”:{“$ref”:”#/definitions/User”}}},”401″:{“description”:”Unauthorized”},”403″:{“description”:”Forbidden”},”404″:{“description”:”Not Found”}},”deprecated”:false},”post”:{“tags”:[“user-resource”],”summary”:”createUser”,”operationId”:”createUserUsingPOST”,”consumes”:[“application/json”],”produces”:[“*/*”],”parameters”:[{“in”:”body”,”name”:”user”,”description”:”user”,”required”:true,”schema”:{“$ref”:”#/definitions/User”}}],”responses”:{“200”:{“description”:”OK”,”schema”:{“type”:”object”}},”201″:{“description”:”Created”},”401″:{“description”:”Unauthorized”},”403″:{“description”:”Forbidden”},”404″:{“description”:”Not Found”}},”deprecated”:false}},  

The above resource contains the two operations get and post that can be performed. We can use get operation to retrieve all the users and post operation to post a user.

Inside the get operation, we get all the response status present there. Response status 200 denotes the successful creation of a user, 401 denotes the unauthorized access of resources, 404 denotes not found, and 403 denotes the forbidden. When we look at the status 200, there is a schema definition. Schema definition shows that we are sending an array of the user as a response. An array of the user is present in the definitions. Similarly, we can also expand the definitions tag to see the definition of the user.

In addition to a POST request, we have parameters that send as part of the body of the request. We accept an input type user as the body of the request.

Expand “/users/{id}” resource:

  “/users/{id}”:{“get”:{“tags”:[“user-resource”],”summary”:”retriveUser”,”operationId”:”retriveUserUsingGET”,”produces”:[“*/*”],”parameters”:[{“name”:”id”,”in”:”path”,”description”:”id”,”required”:true,”type”:”integer”,”format”:”int32″}],”responses”:{“200”:{“description”:”OK”,”schema”:{“$ref”:”#/definitions/Resource«User»”}},”401″:{“description”:”Unauthorized”},”403″:{“description”:”Forbidden”},”404″:{“description”:”Not Found”}},”deprecated”:false},”delete”:{“tags”:[“user-resource”],”summary”:”deleteUser”,”operationId”:”deleteUserUsingDELETE”,”produces”:[“*/*”],”parameters”:[{“name”:”id”,”in”:”path”,”description”:”id”,”required”:true,”type”:”integer”,”format”:”int32″}],”responses”:{“200”:{“description”:”OK”},”204″:{“description”:”No Content”},”401″:{“description”:”Unauthorized”},”403″:{“description”:”Forbidden”}},”deprecated”:false}}},  

The /users/{id} resource allows two operations get and delete. Inside the delete method, there is a parameter called id. This id we are accepting in the path while in the post request, we put content as a part of the body of the request.

Definition defines different kinds of objects that are being used. These definitions are used in the different operations exposed by each resource. When we perform get operation on /users, it returns a list of users. This resource of the user sending back to get the operation of the resource /user/{id} and the resource of the user contains the additional links. The definition of links is also present in the resource of user type.

Links contains a rel and href. A rel is all -users, and href is the link to a particular resource.

There are two ways to expose documentation to the client:

Download the documentation from http://localhost:8080/v2/api-docs as JSON and send it to clients.
Share the link of Swagger UI http://localhost:8080/swagger-ui.html. It is a UI that describes all the operations that are ready to expose.

Click here to download Configuring Auto Generation of Swagger Documentation project

Next TopicEnhancing Swagger Documentation with Custom Annotations

Introduction to Swagger Documentation Format

Introduction to Swagger Documentation Format

Difference between Method Overloading and Method Overriding in java

First JavaFX Application

You may also like