Hello World API in swagger editor

Let's build a simple API that return all the employees information.

API: /employees

Method: GET

Response Code: 200

Response Type: application/json

Open swagger editor, add below yaml content to the 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:
      get:
        responses:
          200:
            description: List of all the employees in organization
            content:
               application/json:
                  schema:
                    type: array
                    items:
                      properties:
                        id:
                          type: integer
                          example: 1234
                        name:
                          type: string
                          example: krishna

Once you added above content to swagger editor, you can see the API details in right side window of the editor.

If you are comfortable in working with json, you can add below snippet to the editor.

{
  "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": {
      "get": {
        "responses": {
          "200": {
            "description": "List of all the employees in organization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "properties": {
                      "id": {
                        "type": "integer",
                        "example": 1234
                      },
                      "name": {
                        "type": "string",
                        "example": "krishna"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Let’s analyse the information that we added in the editor.

openapi: 3.0.0

It tells that we are using openAPI specification 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

Above snippet tells information like

  a. What is title of the application

  b. Short description of the application

  c. Contact information of the exposed API

  d. Version of the API

paths:

Paths object holds the relative paths to the individual endpoints and their operations.

  /employees:
      get:
        responses:
          200:
            description: List of all the employees in organization
            content:
               application/json:
                  schema:
                    type: array
                    items:
                      properties:
                        id:
                          type: integer
                          example: 1234
                        name:
                          type: string
                          example: krishna

/employees: A relative path to get all the employees details. It is a GET API, which return 200 response code and a response body (it is a collection of employees, with employee and name).

Previous                                                    Next                                                    Home