DEV Community

Shoichi Okaniwa
Shoichi Okaniwa

Posted on • Originally published at qiita.com

Remove Examples from Swagger for API Gateway

#javascript #node #aws #swagger

Introduction

I developed an npm library to remove example entries from Swagger files. It is publicly available at the following:

Functionality

Suppose you have a Swagger file with example entries like this:

swagger: '2.0'
info:
  description: This is an API for apartment information.
  version: 0.0.1
  title: Apartment API
paths:
  '/rooms/{room-id}':
    get:
      summary: Room Information API
      description: Returns information for the specified room-id
      parameters:
        - name: room-id
          in: path
          description: The ID of the room you want to retrieve
          required: true
          type: integer
          format: int64
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              id:
                type: integer
                format: int64
                example: 404
              comment:
                type: string
                example: Room 404. It may not exist anywhere.
Enter fullscreen mode Exit fullscreen mode

When you input the above, the output will be as follows:

swagger: '2.0'
info:
  description: This is an API for apartment information.
  version: 0.0.1
  title: Apartment API
paths:
  '/rooms/{room-id}':
    get:
      summary: Room Information API
      description: Returns information for the specified room-id
      parameters:
        - name: room-id
          in: path
          description: The ID of the room you want to retrieve
          required: true
          type: integer
          format: int64
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              id:
                type: integer
                format: int64
              comment:
                type: string
Enter fullscreen mode Exit fullscreen mode

Only example entries are removed! It finds and removes them wherever they are nested.

Why was it created?

When importing a Swagger file into Amazon API Gateway, the following error occurred:

errors : [Invalid model schema specified. Unsupported keyword(s): ["example"]]
Enter fullscreen mode Exit fullscreen mode

Removing example from the definitions in the Swagger file prevents errors with API Gateway, but example is used in Swagger UI.

This led me to create a library to maintain the example entries during regular development and remove them only for API Gateway registration.

Installation

This library requires Node.js. If Node.js is installed, use the following command to install:

npm install swagger-rm-example
Enter fullscreen mode Exit fullscreen mode

Usage

Here is a sample code:

// Add library
var fs = require('fs');
var swaggerRmExample = require('swagger-rm-example');

// Load YAML file
var inputFile = "./swagger_input.yaml";
var strInput = fs.readFileSync(inputFile, 'utf8');

// Remove example from string
var strOutput = swaggerRmExample.removeExample(strInput);

// Display result
console.log(strOutput);

// Write YAML file
var fileOutput = "./swagger_output.yaml";
fs.writeFile(fileOutput, strOutput);
Enter fullscreen mode Exit fullscreen mode

Conclusion

With this, you can enjoy a smooth Swagger experience.

It was my first time publishing a package on npm, but thanks to the following articles, it was much easier than expected:

Top comments (0)