In today’s post, I will explain about how can we design rest apis using Swagger UI.
Swagger is a rest api documenting tool that can be used to documenting all kind of rest apis in an organisation.
The major Swagger tools include:
- Swagger Editor – browser-based editor where you can write OpenAPI specs.
- Swagger UI – renders OpenAPI specs as interactive API documentation.
- Swagger Codegen – generates server stubs and client libraries from an OpenAPI spec.
We can use swagger in following two ways:
- Top down approach
- Bottom Up approach
Top Down Approach
In this kind of approach, we’ll first design all the apis using Swagger UI and then we’ll code for the same.
Pros of this approach
- No need to code and no need to have prior knowledge about how to implement swagger in spring boot project.
- Design all the apis and generate code for your apis automatically by swagger UI itself.
- If your manager ask for the change then no need to change into the code just change in apis and code will be automatically generated.
Cons of this approach
- Need to have knowledge about how to design apis using swagger UI
Bottom Up Approach
In this kind of approach, we’ll first code for the apis and then integrate swagger tool in our spring boot projects and we’ll document our rest apis by using swagger. This approach is most widely used in the organisation and most of the developers just implement apis first and then document it.
Cons of this approach
- Every developers need to have prior knowledge of how to implement swagger in spring boot project.
- Need to know different annoations used in swagger in order to make better documentation.
- After implementing all the apis, if your manager ask for the change then you need to change it in code.
Let’s understand how to design apis using swagger with following example:
Suppose we have a micro-service resource-management which exposes CRUD API’s to manage users and we need to document it using Open API specification and then generate code.
Following are the different HTTP methods to which we need to document our apis:
- GET
- PUT
- POST
- DELETE
To start documenting our apis we need to follow following steps:
- Need to define basic information about the apis
- Server information where this microservice will be deployed
- Defining DTO classes for apis
- Defining all the resource URIs for each apis
- Define signature of all the apis which contains Http Method, parameters, body, http headers etc.
Basic Information about the apis
swagger: "2.0" info: description: "This is an application which provides all the apis required by resource manager in order to maintain resources." version: "1.0.0" title: "Vahana Resource Manager"
Server Information
host: "vahanaresource.threadminions.com" basePath: "/resource-manager/v1" schemes: - "https" - "http"
In this above, host defines the base domain or url where your microservice will be deployed and basepath defines the context path of your all the apis and schems defines the http protocol for your apis.
Define DTO Classes
definitions tag is used for the same.
definitions:
VahanaResource:
type: "object"
required:
- "name"
- "resourceHierarchy"
properties:
name:
type: "string"
description: "name of the resource"
description:
type: "string"
description : "Description for the resource"
systemResourceType:
type: "string"
description: "Type of the resource to which it belongs"
example: "arn:vahana:vconnect:api:rest, arn:vahana:vconnect:api:dbes"
resourceUniqueId:
type: "string"
description: "Unique Id for the resource to identify record uniquelly"
orgId:
type: "string"
description: "Org id to which resource belongs to"
resourceVersion:
type: "string"
description: "version of resource"
environment:
type: "string"
description: "environment of the resource"
example: "SIT/UAT/Pre-prod/Live"
appId:
type: "string"
description: "app id to which resource belongs to"
Define Rest of the things
Below code block defines how to describe your API’s in YAML file
paths:
/resource/create:
post:
summary: "Add a new resource to vahana"
description: "This api is used to add resource in vahana system"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "requestBody"
description: "Resource Object that is to be added to system resource store"
required: true
schema:
$ref: "#/definitions/VahanaResource"
responses:
200:
description: "Created successfully"
400:
description: "Bad request which tells that request body was invalid"
500:
description: "Internal server error"
/resource/fetch/{resourceId}:
get:
summary: "Get a resource on the basis of resource Id"
description: ""
parameters:
- in: "path"
name: "resourceId"
type: string
description: "Unique resource Id to which record will be returned"
required: true
produces:
- application/json
responses:
200:
description: "resource returned successfully"
500:
description: "Internal server error"
404:
description: "Resource not found"
/resource/remove/{resourceId}:
delete:
summary: "Delete a resource by resource id"
description: "It will delete a resource by provided a resource Id"
parameters:
- in: path
name: resourceId
description: "resourceId against which resource will be deleted"
required: true
type: string
produces:
- application/json
responses:
200:
description: "Deleted successfully"
500:
description: "Internal server error"
404:
description: "Resource not found"
/resource/update/{resourceId}:
put:
summary: "Update a resource by resource Id"
description: "It will update a resource on basis oo resource Id"
produces:
- application/json
parameters:
- in: path
name: resourceId
description: "resourceId against which resource will be deleted"
required: true
type: string
- in: body
name: requestBody
required: true
schema:
$ref: '#/definitions/VahanaResource'
responses:
200:
description: "Updated successfully"
500:
description: "Internal server error"
404:
description: "Resource not found"
Consolidating all the information regarding your API as mentioned above, your YAML file looks like –
swagger: "2.0"
info:
description: "This is an application which provides all the apis required by resource manager in order to maintain resources."
version: "1.0.0"
title: "Vahana Resource Manager"
host: "vahanaresource.threadminions.com"
basePath: "/resource-manager/v1"
schemes:
- "https"
- "http"
paths:
/resource/create:
post:
summary: "Add a new resource to vahana"
description: "This api is used to add resource in vahana system"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "requestBody"
description: "Resource Object that is to be added to system resource store"
required: true
schema:
$ref: "#/definitions/VahanaResource"
responses:
200:
description: "Created successfully"
400:
description: "Bad request which tells that request body was invalid"
500:
description: "Internal server error"
/resource/fetch/{resourceId}:
get:
summary: "Get a resource on the basis of resource Id"
description: ""
parameters:
- in: "path"
name: "resourceId"
type: string
description: "Unique resource Id to which record will be returned"
required: true
produces:
- application/json
responses:
200:
description: "resource returned successfully"
500:
description: "Internal server error"
404:
description: "Resource not found"
/resource/remove/{resourceId}:
delete:
summary: "Delete a resource by resource id"
description: "It will delete a resource by provided a resource Id"
parameters:
- in: path
name: resourceId
description: "resourceId against which resource will be deleted"
required: true
type: string
produces:
- application/json
responses:
200:
description: "Deleted successfully"
500:
description: "Internal server error"
404:
description: "Resource not found"
/resource/update/{resourceId}:
put:
summary: "Update a resource by resource Id"
description: "It will update a resource on basis oo resource Id"
produces:
- application/json
parameters:
- in: path
name: resourceId
description: "resourceId against which resource will be deleted"
required: true
type: string
- in: body
name: requestBody
required: true
schema:
$ref: '#/definitions/VahanaResource'
responses:
200:
description: "Updated successfully"
500:
description: "Internal server error"
404:
description: "Resource not found"
definitions:
VahanaResource:
type: "object"
required:
- "name"
- "resourceHierarchy"
properties:
name:
type: "string"
description: "name of the resource"
description:
type: "string"
description : "Description for the resource"
systemResourceType:
type: "string"
description: "Type of the resource to which it belongs"
example: "arn:vahana:vconnect:api:rest, arn:vahana:vconnect:api:dbes"
resourceUniqueId:
type: "string"
description: "Unique Id for the resource to identify record uniquelly"
orgId:
type: "string"
description: "Org id to which resource belongs to"
resourceVersion:
type: "string"
description: "version of resource"
environment:
type: "string"
description: "environment of the resource"
example: "SIT/UAT/Pre-prod/Live"
appId:
type: "string"
description: "app id to which resource belongs to"
To view the swagger UI by using this yml, just copy it and click here to view its documentation.
That’s it for it.
