Design Rest APIs using Swagger

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:

  1. Need to define basic information about the apis
  2. Server information where this microservice will be deployed
  3. Defining DTO classes for apis
  4. Defining all the resource URIs for each apis
  5. 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.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s