Swagger Hub: Versioning of APIs

You can maintain different versions of the APIs using Swagger Hub.

Publish the API

Login to swagger hub (https://app.swaggerhub.com/home).

Click on ‘Create New’ button which is available in left side of the window.

Click on ‘Create New API’

Select OpenAPI Version as 3.0.0., Template as ‘Simple API’ and give the name as ‘Customer’

Click on ‘CREATE API’ button.

It creates new API and navigates to swagger editor.

data.yaml

openapi: 3.0.0
info:
  title: Customer Data Aceess API
  description: API to expose all the CRUD operations on  customers
  contact:
    name: Krishna
    email: krishna123@abc.com
    url: https://self-learning-java-tutorial.blogspot.com/
  version: 1.0.0
paths:

  /employees/{employeeId}:
    get:
      parameters: 
      - in: path
        name: employeeId
        required: true
        schema:
          type: integer
          example: 123
      responses:
        200:
          description: Get Specific Employee Details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/employee'
            application/xml:
              schema:
                $ref: '#/components/schemas/employee'
            application/csv:
              schema:
                $ref: '#/components/schemas/employee'
        403:
          $ref: '#/components/responses/403Unauthorized'
        500:
          $ref: '#/components/responses/500InternalServerError'
          
  /employees:
      post:
        description: Add new employee to the organization
        requestBody:
          content:
            application/json:
              schema:
                type: object
                properties:
                  firstName:
                    type: string
                    example: krishna
                  lastName:
                    type: string
                    example: gurram
        responses:
          201:
            description: New Employee is created
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/employee'
          403:
            $ref: '#/components/responses/403Unauthorized'
          500:
            $ref: '#/components/responses/500InternalServerError'
                  
      get:
        parameters: 
          - $ref: '#/components/parameters/pageSize'
          - $ref: '#/components/parameters/pageNumber'
          - in: header
            name: onetime_token
            description: token to be used at the time of login
            required: false
            schema:
              type: string
              example: 08c3372a-9314-49d6-b9dd-ff212c1715a5
        responses:
          200:
            description: List of all the employees in organization
            content:
               application/json:
                  schema:
                    type: array
                    items:
                      $ref: '#/components/schemas/employee'
          403:
            $ref: '#/components/responses/403Unauthorized'
          500:
            $ref: '#/components/responses/500InternalServerError'

components:
  parameters:
    pageSize:  
      in: query
      name: size
      description: Number of elements to return
      required: false
      schema:
        type: integer
        example: 10
        minimum: 10
        maximum: 100
        
    pageNumber:
      in: query
      name: from
      description: Page number to return
      required: true
      schema:
        type: integer
        example: 1
        
  responses:
    403Unauthorized:
      description: User do not have permission to access this API
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
                example: 403
              message:
                type: string
                example: Unauthorized
    500InternalServerError:
      description: Unable to process the request
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
                example: 500
              message:
                type: string
                example: Internal Server Error
  schemas:
    employee:
      type: object
      required: 
        - firstName
        - id
      properties:
        id:
          type: integer
          example: 1234
        firstName:
          type: string
          example: krishna
        lastName:
          type: string
          example: gurram

Copy the content of data.yaml to swagger editor.

Save the changes by clicking in ‘SAVE’ button.

Click on 1.0.0 -> Publish API button.

It open publish version screen like below.

Click on ‘PUBLISH VERSION’ button.

Once the version is published, document will go to Read Only state.

How to add new version?

Click on 1.0.0.

Click on ‘Add New Version’ button.

Give the API Version value as 2.0.0. Click on ‘CREATE NEW VERSION’ button.

Now you can see version 2.0.0 is created. You can make the changes in swagger editor, save and publish api version 2.0.0.

data.yaml

openapi: 3.0.0
info:
  title: Customer Data Aceess API
  description: API to expose all the CRUD operations on  customers
  contact:
    name: Krishna
    email: krishna123@abc.com
    url: https://self-learning-java-tutorial.blogspot.com/
  version: 1.0.0
paths:

  /employees/{employeeId}:
    get:
      parameters: 
      - in: path
        name: employeeId
        required: true
        schema:
          type: integer
          example: 123
      responses:
        200:
          description: Get Specific Employee Details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/employee'
            application/xml:
              schema:
                $ref: '#/components/schemas/employee'
            application/csv:
              schema:
                $ref: '#/components/schemas/employee'
        403:
          $ref: '#/components/responses/403Unauthorized'
        500:
          $ref: '#/components/responses/500InternalServerError'
          
  /employees:
      post:
        description: Add new employee to the organization
        requestBody:
          content:
            application/json:
              schema:
                type: object
                properties:
                  firstName:
                    type: string
                    example: krishna
                  lastName:
                    type: string
                    example: gurram
        responses:
          201:
            description: New Employee is created
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/employee'
          403:
            $ref: '#/components/responses/403Unauthorized'
          500:
            $ref: '#/components/responses/500InternalServerError'
                  
      get:
        parameters: 
          - $ref: '#/components/parameters/pageSize'
          - $ref: '#/components/parameters/pageNumber'
          - in: header
            name: onetime_token
            description: token to be used at the time of login
            required: false
            schema:
              type: string
              example: 08c3372a-9314-49d6-b9dd-ff212c1715a5
        responses:
          200:
            description: List of all the employees in organization
            content:
               application/json:
                  schema:
                    type: array
                    items:
                      $ref: '#/components/schemas/employee'
          403:
            $ref: '#/components/responses/403Unauthorized'
          500:
            $ref: '#/components/responses/500InternalServerError'

components:
  parameters:
    pageSize:  
      in: query
      name: size
      description: Number of elements to return
      required: false
      schema:
        type: integer
        example: 10
        minimum: 10
        maximum: 100
        
    pageNumber:
      in: query
      name: from
      description: Page number to return
      required: true
      schema:
        type: integer
        example: 1
        
  responses:
    403Unauthorized:
      description: User do not have permission to access this API
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
                example: 403
              message:
                type: string
                example: Unauthorized
    500InternalServerError:
      description: Unable to process the request
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
                example: 500
              message:
                type: string
                example: Internal Server Error
    404NotFoundError:
      description: Service Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
                example: 404
              message:
                type: string
                example: Service not found
  schemas:
    employee:
      type: object
      required: 
        - firstName
        - id
      properties:
        id:
          type: integer
          example: 1234
        firstName:
          type: string
          example: krishna
        lastName:
          type: string
          example: gurram

Update the content with above data.yaml and publish 2.0.0 version.

How to compare versions?

Select any one of the versions, expand it and click on ‘Compare Versions’ button.

Previous                                                    Next                                                    Home