Display API definition in Swagger UI using Docker + Rails6 + apipie

goal

1. Automatically generate a file with API definitions
2. Manage Swagger UI containers with docker-compose
3. View API definition & request / response with Swagger UI in local environment

environment

Ruby: 2.7.1
Rails: 6.0.3

1. Automatically generate a file with API definitions

Introduction

It seemed that the API definition file could be generated with the gem apipie \ -rails, so I used this.

Follow Getting started to add to Gemfile and initialize apipie.

Gemfile

gem "apipie-rails"

$ bundle install
$ rails g apipie:install

apipie.rb is generated and apipie is added to routes.rb.

Document filling

Based on DSL Reference, write the API definition at the top of the method in each Controller. (This is my own work ...)

The following is an implementation example

api/v1/users_controller.rb

class Api::V1::UsersController < ApiController

  api :POST, "/api/v1/users/token", "get access token"
  description "Authenticate login and return token"
  formats ["json"]
  param :email, String, desc: "mail address", required: true
  param :password, String, desc: "password", required: true
  returns code: 200, desc: "return user token"
  error code: 401, desc: "Unauthorized"
  example <<-JSON
    {
      detail: "Token Example",
    }
  JSON

  def token
    #Implementation abbreviation
  end

Generate API definition file

$ rails apipie:static_swagger_json

schema_swagger_form_data.json is generated in doc / apidoc.

2. Manage Swagger UI containers with docker-compose

docker-compose settings

docker-compose.yml

services:
  app:
   (Abbreviation)
  
  swagger-ui:
    image: swaggerapi/swagger-ui
    ports:
      - "8081:8080"
    volumes:
      - doc/apidoc/schema_swagger_form_data.json:/swagger.json
    environment:
      SWAGGER_JSON: /swagger.json

When you start docker and access localhost: 8081, you will be able to read the API definition.

Reference: Run Swagger Editor and Swagger UI with Docker

Adjust apipie.rb

Since the directory structure and port differ depending on the project, adjust apipie.rb if necessary. You can also find more details in the reference Swagger -Specific Configuration Parameters.

apipie.rb

-  config.api_base_url            = "/api"
+  config.api_base_url            = ""
+  config.swagger_api_host = "localhost:3100"

Don't forget to generate the document after the adjustment.

3. View API definition & request / response in Swagger UI of local environment

With the current settings, the API and Swagger UI containers are different, so API requests / responses cannot be made. Set CORS to solve it.

CORS settings

Add the gem of rack \ -cors and add the settings as below.

Gemfile

gem "rack-cors"

config/application.rb

module App
  class Application < Rails::Application
    (Omitted)

    #Add the following
    config.x.request = ActiveSupport::InheritableOptions.new(config_for(:request))

    # Permit cross origin
    config.middleware.insert_before 0, Rack::Cors do
      allow do
        origins Rails.application.config.x.request["domain"]
        resource "*",
        headers: :any,
        methods: [:get, :post, :put, :patch, :delete, :options, :head]
      end
    end
  end
end

config/request.yml

default: &default
  domain:
   - localhost:3100 #app port
   - localhost:8081 # swagger-ui port

development:
  <<: *default

test:
  <<: *default

production:
  domain:

After rewriting, restart the app container and you will be able to make requests from the Swagger UI.

reference: -TypeError: Failed to fetch in Swagger \ -UI and die -[Separate CORS settings for each environment](https://ti-tomo-knowledge.hatenablog.com/entry/2019/07/25/132408#CORS%E3%81%AE%E8%A8%AD% E5% AE% 9A% E3% 82% 92% E7% 92% B0% E5% A2% 83% E3% 81% 94% E3% 81% A8% E3% 81% AB% E5% 88% 86% E3% 81% 91% E3% 82% 8B)