OpenAPI spec. concept

The OpenAPI FAQ provides good explanations for OpenAPI spec. Therefore, we have listed some descriptions below, which give a good overview about this topic.

In case that further knowledge is required, visit openapis.org which provides plenty of useful information.

What is OpenAPI?

«There is the OpenAPI Specification (OAS), a technical specification that describes certain APIs, and there is the OpenAPI Initiative (OAI), an organization that enables specifications like OAS to thrive.

The OAS defines a standard, programming language-agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OAS, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OAS removes guesswork in calling a service.

The OpenAPI Initiative (OAI) was created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how APIs are described. As an open governance structure under the Linux Foundation, the OAI is focused on creating, evolving and promoting a vendor neutral description format. The OpenAPI Specification was based on the rebranded Swagger 2.0 specification, donated by SmartBear Software in 2015. »

Source:

(openapis.org) OpenAPI FAQ

What are the main benefits of the OpenAPI Specification?

«Business benefits are:

  • The OpenAPI Specification (OAS) is backed by an impressive group of industry leaders, representing strong awareness and mindshare in the industry.
  • OAS is widely recognized as the most popular open source framework for defining and creating RESTful APIs, and today tens of thousands of developers are building thousands of open source repos of tools leveraging the OAS.
  • This wide level of industry support is also a strong indication of stability across a substantial and diverse code base today and suggests a promising future.

Technical benefits are:

  • With the OAS’s declarative resource specification, clients can understand and consume services without knowledge of server implementation or access to the server code.
  • OAS is language-agnostic.
  • OAS has great documentation, support, and individual experts who are involved in the community. OAS not only has broad industry support, but it has a long history with a large, energetic, talented community and support base. There are many ways of connecting with talented individuals to find example implementations, code snippets and specifical answers.»
Source:

(openapis.org) OpenAPI FAQ

Example OpenAPI specification

This example illustrates how an OpenAPI specification could look like:

Show moreShow less
{ 
  "openapi": "3.0.0", 
  "info": { 
    "version": "1.0.0", 
    "title": "Swagger Petstore", 
    "license": { 
      "name": "MIT" 
    } 
  }, 
  "servers": [ 
    { 
      "url": "http://petstore.swagger.io/v1" 
    } 
  ], 
  "paths": { 
    "/pets": { 
      "get": { 
        "summary": "List all pets", 
        "operationId": "listPets", 
        "tags": [ 
          "pets" 
        ], 
        "parameters": [ 
          { 
            "name": "limit", 
            "in": "query", 
            "description": "How many items to return at one time (max 100)", 
            "required": false, 
            "schema": { 
              "type": "integer", 
              "format": "int32" 
            } 
          } 
        ], 
        "responses": { 
          "200": { 
            "description": "A paged array of pets", 
            "headers": { 
              "x-next": { 
                "description": "A link to the next page of responses", 
                "schema": { 
                  "type": "string" 
                } 
              } 
            }, 
            "content": { 
              "application/json": { 
                "schema": { 
                  "$ref": "#/components/schemas/Pets" 
                } 
              } 
            } 
          }, 
          "default": { 
            "description": "unexpected error", 
            "content": { 
              "application/json": { 
                "schema": { 
                  "$ref": "#/components/schemas/Error" 
                } 
              } 
            } 
          } 
        } 
      }, 
      "post": { 
        "summary": "Create a pet", 
        "operationId": "createPets", 
        "tags": [ 
          "pets" 
        ], 
        "responses": { 
          "201": { 
            "description": "Null response" 
          }, 
          "default": { 
            "description": "unexpected error", 
            "content": { 
              "application/json": { 
                "schema": { 
                  "$ref": "#/components/schemas/Error" 
                } 
              } 
            } 
          } 
        } 
      } 
    }, 
    "/pets/{petId}": { 
      "get": { 
        "summary": "Info for a specific pet", 
        "operationId": "showPetById", 
        "tags": [ 
          "pets" 
        ], 
        "parameters": [ 
          { 
            "name": "petId", 
            "in": "path", 
            "required": true, 
            "description": "The id of the pet to retrieve", 
            "schema": { 
              "type": "string" 
            } 
          } 
        ], 
        "responses": { 
          "200": { 
            "description": "Expected response to a valid request", 
            "content": { 
              "application/json": { 
                "schema": { 
                  "$ref": "#/components/schemas/Pet" 
                } 
              } 
            } 
          }, 
          "default": { 
            "description": "unexpected error", 
            "content": { 
              "application/json": { 
                "schema": { 
                  "$ref": "#/components/schemas/Error" 
                } 
              } 
            } 
          } 
        } 
      } 
    } 
  }, 
  "components": { 
    "schemas": { 
      "Pet": { 
        "type": "object", 
        "required": [ 
          "id", 
          "name" 
        ], 
        "properties": { 
          "id": { 
            "type": "integer", 
            "format": "int64" 
          }, 
          "name": { 
            "type": "string" 
          }, 
          "tag": { 
            "type": "string" 
          } 
        } 
      }, 
      "Pets": { 
        "type": "array", 
        "items": { 
          "$ref": "#/components/schemas/Pet" 
        } 
      }, 
      "Error": { 
        "type": "object", 
        "required": [ 
          "code", 
          "message" 
        ], 
        "properties": { 
          "code": { 
            "type": "integer", 
            "format": "int32" 
          }, 
          "message": { 
            "type": "string" 
          } 
        } 
      } 
    } 
  } 
}