elevennines-inc / swagger-all-in-one-docker-compose

swagger-all-in-one-docker-container

Overview

I docker composed Swagger Editor, Swagger UI, Swagger mock api server(openapi: 3.x) and nginx to handle them more easily. If you want to write swagger spec as swagger: "2.0", use swagger2.0 branch. There is a sample swagger spec in this so the Editor, UI and the mock API server will run without any configuration from the start. All you need to do is edit the swagger spec, save as openapi.json, and restart docker. Voila, UI and the mock API server are updated.

How to Run

docker-compose up -d

It will look like this.
docker-compose ps
         Name                       Command               State           Ports
----------------------------------------------------------------------------------------
swagger-api      /usr/local/bin/apisprout / ...   Up      0.0.0.0:8083->8000/tcp
swagger-editor   sh /usr/share/nginx/docker ...   Up      0.0.0.0:8081->8080/tcp
swagger-nginx    nginx -g daemon off;             Up      80/tcp, 0.0.0.0:8084->8084/tcp
swagger-ui       sh /usr/share/nginx/docker ...   Up      0.0.0.0:8082->8080/tcp

How to Use

1. Edit swagger spec with swagger-editor
2. Save swagger spec as json from swagger-editor File menu
3. Move and save the json file as swagger/openapi.json
4. Execute docker-compose restart and swagger-ui and swagger-api(mock server) will be updated
5. If you want to read an external openapi.json file, import the file from swagger-editor File > Import File menu.

Heads-up

• When the UI is referenced as http://localhost:8082/, cache might be used even the changes are made in swagger files. So it may be better to refference as http://127.0.0.1:8082/(api, too.)
• When swagger-api failed to run, it's likely that api server failed to run because the openapi.json was not properly read. So use docker logs command and get rid of the cause then restart it again.
• If you want to access swagger-api from other domains(CORS), access swagger-api through swagger-nginx.

swagger-editor

• Can edit swagger spec
• Can export swagger spec as json, yaml and etc. swagger-ui can read the files and they can be beautifly referenced as documentation. apisprout can read the yml and json then it can serve the mock API.

swagger-ui

• Can referrence the documentation from swagger spec.
• swagger spec can be assined from json file path or API_URL path.

environment:
  SWAGGER_JSON: /openapi.json
  # API_URL: ""

• ./swagger/openapi.json is refferenced in this repository

swagger-api(apisprout)

• Internally using apisprout in docker.
• swagger spec is compatible with openapi: 3.x.
• ./swagger/openapi.json is also refferenced from api in this repository.
• However, apisprout can not add Access-Control-Allow-Origin to Header so I put nginx in front of swagger-api and add it to Header then proxy to swagger-api.(To make it accessable from othe domains. CORS.)

swagger-nginx

• Placed to modify Header.

• Mock API(swagger-api) can be accessed from 8084 port via nginx.

• Of course, you can use the api from curl, etc.

  * example
  curl -i -X GET http://127.0.0.1:8084/pets/1 -H "accept: application/json"
  
  HTTP/1.1 200 OK
  Server: nginx/1.15.3
  Date: Thu, 04 Oct 2018 07:58:19 GMT
  Content-Type: application/json
  Content-Length: 49
  Connection: keep-alive
  Access-Control-Allow-Origin: *
  Access-Control-Allow-Methods: POST, GET, PATCH, DELETE, PUT, OPTIONS
  Access-Control-Allow-Headers: Origin, Authorization, Accept
  Access-Control-Allow-Credentials: true
  
  {
    "id": 1,
    "name": "doggie",
    "tag": "dog"
  }

swagger-all-in-one-docker-compose's Issues

ymlでモックサーバを動かしたい

初めまして。
swagger-all-in-one-docker-compose の利用者です。
jsonではなく、ymlでモックサーバーを起動したいのですが、
docker-compose.ymlをどのように書き換えれば良いか教えていただけないでしょうか。
よろしくお願い致します。

swagger editor does not read automatically from openapi.json

Maybe swagger editor has been updated and swagger editor does not read automatically from openapi.json now because the docker-compose try to pull the latest branch. And I haven't looked the file path to import the openapi.json automatically.
Use File > Import File. Or D&D the openapi.json on the window.
sorry

Un-Reachable mock server.

Hi

I have started using this docker compose project, and the Swagger Editor is up and running, as well as the published page. I am able to edit and test API using both.

However, the mock server, is not reachable.

As you can see if I check the status of all containers they are running

$docker ps 

CONTAINER ID        IMAGE                       COMMAND                  CREATED             STATUS              PORTS                            NAMES
e72a891db1b6        swaggerapi/swagger-ui       "sh /usr/share/nginx…"   3 hours ago         Up About a minute   80/tcp, 0.0.0.0:8082->8080/tcp   swagger-ui
d53b1602badb        swaggerapi/swagger-editor   "sh /usr/share/nginx…"   3 hours ago         Up About a minute   0.0.0.0:8081->8080/tcp           swagger-editor
f628d8d514cc        danielgtaylor/apisprout     "/usr/local/bin/apis…"   3 hours ago         Up About a minute   0.0.0.0:8083->8000/tcp           swagger-api

openapi.json

{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "Swagger Petstore",
    "license": {
      "name": "MIT"
    }
  },
  "servers": [
    {
      "url": "http://petstore.swagger.io/v1"
    },
    {
      "url": "http://localhost:8083/v1"
    }
  ],
  "paths": {
    "/pets": {
      "get": {
        "summary": "List all pets",
        "operationId": "listPets",
        "tags": [
          "pets"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "How many items to return at one time (max 100)",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A paged array of pets",
            "headers": {
              "x-next": {
                "description": "A link to the next page of responses",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pets"
                }
              }
            }
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a pet",
        "operationId": "createPets",
        "tags": [
          "pets"
        ],
        "responses": {
          "201": {
            "description": "Null response"
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/pets/{petId}": {
      "get": {
        "summary": "Info for a specific pet",
        "operationId": "showPetById",
        "tags": [
          "pets"
        ],
        "parameters": [
          {
            "name": "petId",
            "in": "path",
            "required": true,
            "description": "The id of the pet to retrieve",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Expected response to a valid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pets"
                }
              }
            }
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pet": {
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "name": {
            "type": "string"
          },
          "tag": {
            "type": "string"
          }
        }
      },
      "Pets": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/Pet"
        }
      },
      "Error": {
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "format": "int32"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}

But it fails through curl, with both URLs

curl -i -X GET "http://192.168.99.100:8083/v1/pets" -H "accept: application/json"

curl -X GET "http://localhost:8083/v1/pets" -H "accept: application/json"
HTTP/1.1 404 Not Found
Date: Fri, 31 Aug 2018 15:26:35 GMT
Content-Length: 0

Am I missing something ?

Error: network swagger_link declared as external, but could not be found

When I run docker-compose up -d command it throws this error:

network swagger_link declared as external, but could not be found.

Running Docker version 20.10.11, build dea9396 in intel mac.

Missing step in the README documentation

I copied the repo and I hit an error that non-seasoned docker user may block on. The docker network swagger_link is external, and has to be created manually docker network create swagger_link before we run docker-compose up -d