https://github.com/abtris/swagger-manage-extensions

Manage Swagger API Document and Swagger Extensions for AWS API Gateway
https://github.com/abtris/swagger-manage-extensions

Last synced: about 1 month ago
JSON representation

Manage Swagger API Document and Swagger Extensions for AWS API Gateway

• Host: GitHub
• URL: https://github.com/abtris/swagger-manage-extensions
• Owner: abtris
• License: mit
• Created: 2016-05-19T09:48:59.000Z (over 8 years ago)
• Default Branch: master
• Last Pushed: 2023-04-17T05:55:31.000Z (over 1 year ago)
• Last Synced: 2024-08-10T10:51:22.655Z (3 months ago)
• Language: JavaScript
• Homepage:
• Size: 62.5 KB
• Stars: 2
• Watchers: 3
• Forks: 1
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# Swagger Manage Extensions

[![Build Status](https://github.com/abtris/swagger-manage-extensions/actions/workflows/node.js.yaml/badge.svg)](https://github.com/abtris/swagger-manage-extensions/actions)

This tool help have separate definition API and AWS API Gateway into 2 files and merge them for usage in AWS API Gateway.

## Installation

```console

npm install swagger-manage-extensions

```

## Usage

We have separate API in Swagger format and definition for AWS Gateway Integration in another file:

### Swagger file

```yml

---

swagger: "2.0"

info:

  version: "2016-04-29T09:09:33Z"

  title: "api-client"

host: "api-behind-aws-gateway.example.com"

schemes:

- "https"

paths:

  /get/{vanity}:

    get:

      produces:

      - "application/json"

      parameters:

      - name: "authentication"

        in: "header"

        required: true

        type: "string"

      - name: "vanity"

        in: "path"

        required: true

        type: "string"

      responses:

        200:

          description: "200 response"

          schema:

            $ref: "#/definitions/apiClientReponse"

  /publish/{vanity}:

    post:

      produces:

      - "application/json"

      parameters:

      - name: "content_type"

        in: "header"

        required: false

        type: "string"

      - name: "authentication"

        in: "header"

        required: true

        type: "string"

      - name: "accept"

        in: "header"

        required: false

        type: "string"

      - name: "vanity"

        in: "path"

        required: true

        type: "string"

      - name: "user_agent"

        in: "header"

        required: false

        type: "string"

      responses:

        200:

          description: "200 response"

          schema:

            $ref: "#/definitions/apiClientReponse"

definitions:

  apiClientReponse:

    type: "object"

    required:

    - "code"

    - "error"

    - "message"

    properties:

      error:

        type: "boolean"

      message:

        type: "string"

      code:

        type: "string"

```

### Extensions definitions file

```yml

---

paths:

  /get/{vanity}:

    get:

      x-amazon-apigateway-integration:

        responses:

          default:

            statusCode: "200"

        requestParameters:

          integration.request.path.vanity: "method.request.path.vanity"

          integration.request.header.authentication: "method.request.header.authentication"

        httpMethod: "GET"

        uri: "https://api.example.com/get/{vanity}"

        type: "http"

  /publish/{vanity}:

    post:

      x-amazon-apigateway-integration:

        responses:

          default:

            statusCode: "200"

        requestParameters:

          integration.request.path.vanity: "method.request.path.vanity"

          integration.request.header.authentication: "method.request.header.authentication"

        httpMethod: "POST"

        uri: "https://api.example.com/publish/{vanity}"

        type: "http"

```

We don't need integration details in generated documentation (for example: [apiary.io](https://apiary.io)).

### Import to AWS API Gateway

Out scripts merge files together and after than import them into AWS API Gateway.

```js

var sme = require('swagger-manage-extensions');

var fs = require('fs');

var apiPath = "./test/fixtures/api.yml";

var extensionsPath = "./test/fixtures/extensions.yml";

fs.writeFileSync('api-full.yml', sme.merge( apiPath, extensionsPath));

```

Import to AWS API Gateway using [awscli](https://aws.amazon.com/cli/).

```console

aws apigateway put-rest-api  --rest-api-id $1 --mode overwrite --parameters {\"extensions\":\"integrations\"} --body file://./api.json

```

### Export from AWS API Gateway

Export swagger file from AWS API Gateway using [awscli](https://aws.amazon.com/cli/).

```console

aws apigateway get-export --parameters {\"extensions\":\"integrations\"} --rest-api-id $1 --stage-name $2 --export-type swagger --accepts application/yml api.yml

```

You can use tool to split files:

```js

var sme = require('swagger-manage-extensions');

var fs = require('fs');

var apiPath = "./test/fixtures/expected.yml";

var output = sme.split(apiPath);

fs.writeFileSync('extensions.yml', output.extensions);

fs.writeFileSync('api.yml', output.api);

```

### CLI

```console

bin/sme split api-full.yml api.yml extensions.yml

```

```console

bin/sme merge api.yml extensions.yml api-full.yml

```