Zeigen Sie die API-Definition in der Swagger-Benutzeroberfläche mit Docker + Rails6 + apipie an

Tor

1. Generieren Sie automatisch eine Datei mit API-Definitionen
2. Verwalten Sie Swagger UI-Container mit Docker-Compose
3. API-Definitionen in der Swagger-Benutzeroberfläche in der lokalen Umgebung anzeigen und anfordern / beantworten

Umgebung

Ruby: 2.7.1
Rails: 6.0.3

1. Generieren Sie automatisch eine Datei mit API-Definitionen

Einführung

Es schien möglich zu sein, eine API-Definitionsdatei mit einem Juwel namens apipie \ -rails zu generieren, also habe ich diese verwendet.

Folgen Sie Erste Schritte, um die Gemfile hinzuzufügen und die Apipie zu initialisieren.

Gemfile

gem "apipie-rails"

$ bundle install
$ rails g apipie:install

apipie.rb wird generiert und apipie wird zu route.rb hinzugefügt.

Dokumentenfüllung

Schreiben Sie basierend auf der DSL-Referenz die API-Definition oben in die Methode in jedem Controller. (Dies ist meine eigene Arbeit ...)

Das Folgende ist ein Implementierungsbeispiel

api/v1/users_controller.rb

class Api::V1::UsersController < ApiController

  api :POST, "/api/v1/users/token", "get access token"
  description "Authentifizieren Sie die Anmeldung und geben Sie das Token zurück"
  formats ["json"]
  param :email, String, desc: "Mail Adresse", required: true
  param :password, String, desc: "Passwort", required: true
  returns code: 200, desc: "return user token"
  error code: 401, desc: "Unauthorized"
  example <<-JSON
    {
      detail: "Token Example",
    }
  JSON

  def token
    #Implementierung weggelassen
  end

Generieren Sie eine API-Definitionsdatei

$ rails apipie:static_swagger_json

schema_swagger_form_data.json wird in doc / apidoc generiert.

2. Verwalten Sie Swagger UI-Container mit Docker-Compose

Docker-Compose-Einstellungen

docker-compose.yml

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

Wenn Sie Docker starten und auf localhost: 8081 zugreifen, können Sie die API-Definition lesen.

Referenz: Swagger Editor und Swagger UI mit Docker ausführen

Passen Sie apipie.rb an

Da sich die Verzeichnisstruktur und der Port je nach Projekt unterscheiden, passen Sie bei Bedarf apipie.rb an. Weitere Informationen finden Sie auch in der Referenz Swagger \ -Spezifische Konfigurationsparameter.

apipie.rb

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

Vergessen Sie nicht, das Dokument nach der Anpassung zu generieren.

3. Anzeigen und Anfordern / Beantworten von API-Definitionen in der Swagger-Benutzeroberfläche in der lokalen Umgebung

Mit den aktuellen Einstellungen unterscheiden sich die API- und Swagger-UI-Container, sodass API-Anforderungen / -Antworten nicht möglich sind. Stellen Sie CORS ein, um es zu lösen.

CORS-Einstellungen

Fügen Sie den Edelstein für [Rack \ -Cors] hinzu (https://github.com/cyu/rack-cors) und fügen Sie die Einstellungen wie unten gezeigt hinzu.

Gemfile

gem "rack-cors"

config/application.rb

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

    #Fügen Sie Folgendes hinzu
    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:

Starten Sie nach dem Umschreiben den App-Container neu und Sie können Anforderungen über die Swagger-Benutzeroberfläche stellen.

Referenz:

• TypeError: Fehler beim Abrufen von Swagger \ -UI und Sterben
• [CORS-Einstellungen nach Umgebung trennen](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)