Swagger Research

Resources

About swagger: https://swagger.io/docs/specification/about/

Basic YAML structure: https://swagger.io/docs/specification/2-0/basic-structure/

Swagger Specification

Swagger (OpenAPI) is an open-source specification that allows to describe an API based on its:

• Available paths
• Available operations for each path
• Input/Ouput for each operation
• Auth methods

YAML structure

Swagger definitions are JSON or YAML files that can both human and machine readable. An sample Swagger file is as follows:

swagger: "2.0"
info: 
    version: "1.0.0"
    title: "Swagger Petstore"
    description: "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification"
    termsOfService: "http://swagger.io/terms/"
    contact: 
      name: "Swagger API Team"
    license: 
      name: "MIT"
host: "petstore.swagger.io"
basePath: "/api"
schemes: 
    - "http"
consumes: 
    - "application/json"
produces: 
    - "application/json"
paths: 
    /pets: 
      get: 
        description: "Returns all pets from the system that the user has access to"
        produces: 
          - "application/json"
        responses: 
          "200":
            description: "A list of pets."
            schema: 
              type: "array"
              items: 
                $ref: "#/definitions/Pet"
definitions: 
    Pet: 
      type: "object"
      required: 
        - "id"
        - "name"
      properties: 
        id: 
          type: "integer"
          format: "int64"
        name: 
          type: "string"
        tag: 
          type: "string"

While a request body schema can be written inside the path object, our solution will use references. We insert a reference into an endpoint like so:

path:
  /endpoint:
    post:
      requestbody:
        content:
          application/json:
            schema:
              $ref: "schemaname"

In another part of the file, we define the schema like so:

components:
  schemas: 
    schemaname:
      { Structure generated by parsing JSON schemas }