OpenAPI-AWS-Decorator

This will decorate an Open API v3 document with specific x-amazon- OpenAPI syntax.

Install

To install: Using npm:

npm install openapi-aws-decorator

Usage

x-amazon-apigateway-documentation

To decorate an OpenAPI file with x-amazon-apigateway-documentation, which are Documentation Parts you can run this code:

const OpenAPIDecorator = require("openapi-aws-decorator");

const openAPI = {
  openapi: "3.0.1",
  info: {
    description:
      "The Data Set API (DSAPI) allows the public users to discover and search USPTO exported data sets. This is a generic API that allows USPTO users to make any CSV based data files searchable through API. With the help of GET call, it returns the list of data fields that are searchable. With the help of POST call, data can be fetched based on the filters on the field names. Please note that POST call is used to search the actual data. The reason for the POST call is that it allows users to specify any complex search criteria without worry about the GET size limitations as well as encoding of the input parameters.",
    version: "1.0.0",
    title: "USPTO Data Set API",
    contact: {
      name: "Open Data Portal",
      url: "https://developer.uspto.gov",
      email: "[email protected]",
    },
  },
  paths: {
    "/": {
      get: {
        operationId: "list-data-sets",
        summary: "List available data sets",
        responses: {
          200: {
            description: "Returns a list of data sets",
            content: {
              "application/json": {
                schema: {
                  $ref: "#/components/schemas/responseData",
                },
              },
            },
          },
        },
      },
    },
  },
  components: {
    schemas: {
      responseData: {
        type: "string",
      },
    },
  },
};

const openAPIDecorator = new OpenAPIDecorator(openAPI);
openAPIDecorator.decorate();

console.log(openAPIDecorator.openAPI);

This will end up with the original OpenAPI document containing a new property section of x-amazon-apigateway-documentation with the various Documentation Parts listed out.

{
  "openapi": "3.0.1",
  "info": {
    "description": "The Data Set API (DSAPI) allows the public users to discover and search USPTO exported data sets. This is a generic API that allows USPTO users to make any CSV based data files searchable through API. With the help of GET call, it returns the list of data fields that are searchable. With the help of POST call, data can be fetched based on the filters on the field names. Please note that POST call is used to search the actual data. The reason for the POST call is that it allows users to specify any complex search criteria without worry about the GET size limitations as well as encoding of the input parameters.",
    "version": "1.0.0",
    "title": "USPTO Data Set API",
    "contact": {
      "name": "Open Data Portal",
      "url": "https://developer.uspto.gov",
      "email": "[email protected]"
    }
  },
  ...
  "x-amazon-apigateway-documentation": {
    "version": "1.0.0",
    "documentationParts": [
      {
        "location": { "type": "API" },
        "properties": {
          "description": "The Data Set API (DSAPI) allows the public users to discover and search USPTO exported data sets. This is a generic API that allows USPTO users to make any CSV based data files searchable through API. With the help of GET call, it returns the list of data fields that are searchable. With the help of POST call, data can be fetched based on the filters on the field names. Please note that POST call is used to search the actual data. The reason for the POST call is that it allows users to specify any complex search criteria without worry about the GET size limitations as well as encoding of the input parameters.",
          "version": "1.0.0",
          "title": "USPTO Data Set API",
          "contact": {
            "name": "Open Data Portal",
            "url": "https://developer.uspto.gov",
            "email": "[email protected]"
          }
        }
      },
      { "location": { "type": "RESOURCE", "path": "/" }, "properties": {} },
      {
        "location": { "type": "METHOD", "path": "/", "method": "get" },
        "properties": { "summary": "List available data sets" }
      },
      {
        "location": {
          "path": "/",
          "method": "get",
          "statusCode": "200",
          "type": "RESPONSE"
        },
        "properties": { "description": "Returns a list of data sets" }
      }
    ]
  }
}

You can then use the AWS CLI v2 command to upload the documentation parts:

aws apigateway import-documentation-parts --rest-api-id your-rest-api-id --body fileb://openAPI.json

This asusmes that you have saved the augmented OpenAPI to a file called openAPI.json and that you know your rest-api-id.