velmie/openapi-renderer repository overview

⁠OpenAPI-renderer

⁠Table of Contents

• Summary⁠
• Requirements⁠
• Setup⁠
  • S3⁠
  • Config⁠
  • Authentication⁠
• Run locally⁠
  • The Docker way⁠

⁠Summary

• Automatically scans S3 bucket for openapi.yml files, and populates service/version dropdown menus
• Displays documentation using ReDoc⁠, based on the selected service/version

⬆ back to top⁠

⁠Requirements

• Node.js 8.x
• npm 6.9.0

⬆ back to top⁠

⁠Setup

⁠S3

Should have a bucket on AWS S3⁠ with the following structure:

    [BUCKET]
    |__[STAGE]
       |__[SERVICE]
          |__[TIMESTAMP-VERSION] || [VERSION-TIMESTAMP] || [TIMESTAMP] || [VERSION] 
             |__openapi.yml
   

• BUCKET - bucket for documentation;
• STAGE - application development stage (example: dev, stage, prod);
• SERVICE - service name;
• VERSION - version;
• TIMESTAMP - timestamp;
• openapi.yml - .yml document;

For example:

    bucket-api-documentation
    |___dev
    |   |___mobileApp
    |   |   |___1572347149-v1.0.0 
    |   |   |   |___openapi.yml    
    |   |   |___1573159917
    |   |       |___openapi.yml
    |   |
    |   |___backendApp 
    |       |___v1.0.0-1572347149
    |       |   |___openapi.yml   
    |       |___v1.0.0 
    |           |___openapi.yml 
    |
    |___stage
        |___mobileApp   
        |   |___v1.0.0-1572347149
        |       |___openapi.yml
        |
        |___frontendApp 
            |___v1.0.1
            |   |___openapi.yml   
            |___v1.0.0 
                |___openapi.yml   

⬆ back to top⁠

⁠Config

• Required environment variables:
  • S3_AWS_ACCESS_KEY_ID
  • S3_AWS_SECRET_ACCESS_KEY
  • S3_BUCKET
• Optional environment variables (filled by default):
  • PORT = 3000
  • CACHE_TTL = 60000 //60s
  • CACHE_MAX_SIZE = 50 * 1024 * 1024 //50mb
  • S3_API_VERSION = '2006-03-01'
  • S3_OBJECTS_PER_PAGE = 1000
  • COOKIE_TTL = 2592000000 //1month
  • AUTH_USER = ""
  • AUTH_PASS = ""

⬆ back to top⁠

⁠Authentication

Express-basic-auth⁠ - built-in middleware for authorization. You can specify environment variables:

• AUTH_USER
• AUTH_PASS

If you don't specify environment variables then authorization will be missing

⬆ back to top⁠

⁠Run locally

1. npm install
2. cp .env.sample .env
3. (Modify .env)
4. npm start

⁠For debug:

DEBUG=openapi-renderer:* npm start

⁠Starting the system:

localhost:3000

⁠The Docker way

velmie/openapi-renderer⁠

docker pull velmie/openapi-renderer:1.2.1

docker run -p 3000:80 -e S3_AWS_ACCESS_KEY_ID="" -e S3_AWS_SECRET_ACCESS_KEY="" -e S3_BUCKET="" velmie/openapi-renderer:1.2.1

• Required environment variables:
  • S3_AWS_ACCESS_KEY_ID
  • S3_AWS_SECRET_ACCESS_KEY
  • S3_BUCKET
• Optional environment variables for authentication⁠:
  • AUTH_USER
  • AUTH_PASS

⬆ back to top⁠