Using Open API 2.0

The Open API 2.0 specification, also known as Swagger (https://www.openapis.org/) is a simple description language that comes as a JSON or YAML file, that lists all your HTTP API endpoints, how they are used, and the structure of the data that comes in and out. It makes the assumption that your service sends and receives JSON documents.

Swagger has the same goal that WSDL (https://en.wikipedia.org/wiki/Web_Services_Description_Language) had back in the XML web services era, but it's much lighter and straight to the point.

The following example is a minimal Open API description file which defines one single /apis/users_ids endpoint and supports the GET method to retrieve the list of user IDs:

swagger: "2.0" 
info: 
  title: Runnerly Data Service 
  description: returns info about Runnerly 
  license: 
    name: APLv2 
    url: https://www.apache.org/licenses/LICENSE-2.0.html 
  version: 0.1.0 
basePath: /api 
paths: 
    /user_ids: 
      get: 
        operationId: getUserIds...