Sample API Specification

In this article

Reference

Use the following API Specification as a sample.  Download the sample specification.

Demo Swagger
{
  "info": {
    "version": "1.0",
    "description": "This API can be used to Create, Read, Modify & Delete Users",
    "title": "Users"
  },
  "paths": {
    "/createUser": {
      "post": {
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "type": "object",
              "properties": {
                "userName": {
                  "type": "string"
                }
              }
            }
          }
        },
        "parameters": [],
        "produces": [
          "application/json"
        ]
      }
    },
    "/getUsers": {
      "get": {
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "type": "object",
              "properties": {
                "users": {
                  "type": "object"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "description": "User Tags to filter by",
            "items": {
              "type": "string"
            },
            "default": [
              "basic"
            ],
            "required": true,
            "name": "tags",
            "in": "query",
            "type": "array",
            "collectionFormat": "multi"
          },
          {
            "description": "User Types to filter by",
            "default": [
              "basic"
            ],
            "items": {
              "type": "string"
            },
            "required": true,
            "name": "types",
            "in": "query",
            "type": "array",
            "collectionFormat": "multi"
          },
          {
            "description": "Client Secret to filter by",
            "in": "header",
            "required": false,
            "type": "string",
            "name": "secret"
          }
        ],
        "produces": [
          "application/json"
        ]
      }
    },
    "/getUser/{userId}": {
      "get": {
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "type": "object",
              "properties": {
                "user": {
                  "type": "object"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "userId",
            "description": "ID of user that needs to be fetched",
            "required": true,
            "type": "integer",
            "format": "int64"
          }
        ],
        "produces": [
          "application/json"
        ]
      }
    },
    "/updateUser/{userId}": {
      "patch": {
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "type": "object",
              "properties": {
                "user": {
                  "type": "object"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "userId",
            "description": "ID of user that needs to be fetched",
            "required": true,
            "type": "integer",
            "format": "int64"
          }
        ],
        "produces": [
          "application/json"
        ]
      },
      "put": {
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "type": "object",
              "properties": {
                "user": {
                  "type": "object"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "userId",
            "description": "ID of user that needs to be fetched",
            "required": true,
            "type": "integer",
            "format": "int64"
          }
        ],
        "produces": [
          "application/json"
        ]
      },
      "post": {
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "type": "object",
              "properties": {
                "user": {
                  "type": "object"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "userId",
            "description": "ID of user that needs to be fetched",
            "required": true,
            "type": "integer",
            "format": "int64"
          }
        ],
        "produces": [
          "application/json"
        ]
      }
    },
    "/deleteUser/{userId}": {
      "delete": {
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "userId",
            "description": "ID of user that needs to be fetched",
            "required": true,
            "type": "integer",
            "format": "int64"
          }
        ],
        "produces": [
          "application/json"
        ]
      }
    }
  },
  "schemes": [
    "https"
  ],
  "tags": [
    {
      "externalDocs": {
        "url": "http://users.io",
        "description": "Find out more about our Users"
      },
      "name": "Users",
      "description": "Operations about user"
    }
  ],
  "basePath": "/mock/api/path",
  "securityDefinitions": {
    "basicAuth": {
      "type": "basic"
    }
  },
  "host": "sm-mbp-testSpecification:9503",
  "security": [
    {
      "basicAuth": []
    }
  ],
  "swagger": "2.0"
}

Pipeline Generated from Specification

When you create an API version by referencing an OAS specification, the pipeline that is generated maps the elements in the path. The generated pipeline even extracts the dynamic path variables in the endpoints.

The generated Pipeline provides the skeleton for your API with the following design:

Pipeline Framework

When you create an API using the OAS specification for Swagger PetStore API, a pipeline is generated. For example, for the Pet API, the following pipeline is automatically generated.

Endpoint Mappings

In the Router Snap, we can see the various PetStore API endpoints:

  • POST /pet/{petId}/uploadImage

  • POST /pet

  • PUT /pet

  • GET /pet/findByStatus

  • GET /pet/findByTags

  • GET /pet/{petId}

  • POST /pet/{petId}

  • DELETE /pet/{petId}

You can see in the following image how the Router maps each endpoint.

The use of brackets {} indicates that the dynamic value is intentional (as opposed to a variable).