Afficher la définition d'API dans l'interface utilisateur Swagger à l'aide de Docker + Rails6 + apipie

objectif

1. Générez automatiquement un fichier avec des définitions d'API
2. Gérez les conteneurs de l'interface utilisateur Swagger avec docker-compose
3. Afficher et demander / répondre aux définitions d'API dans l'interface utilisateur Swagger dans l'environnement local

environnement

Ruby: 2.7.1
Rails: 6.0.3

1. Générez automatiquement un fichier avec des définitions d'API

introduction

Il semblait possible de générer un fichier de définition d'API avec un gem appelé apipie \ -rails, donc j'ai utilisé ceci.

Suivez Getting started pour ajouter au Gemfile et initialiser l'apipie.

Gemfile

gem "apipie-rails"

$ bundle install
$ rails g apipie:install

«apipie.rb» est généré et «apipie» est ajouté à «routes.rb».

Remplissage de documents

En vous basant sur la Référence DSL, écrivez la définition d'API en haut de la méthode dans chaque contrôleur. (Ceci est mon propre travail ...)

Voici un exemple de mise en œuvre

api/v1/users_controller.rb

class Api::V1::UsersController < ApiController

  api :POST, "/api/v1/users/token", "get access token"
  description "Authentifier la connexion et renvoyer le jeton"
  formats ["json"]
  param :email, String, desc: "adresse mail", required: true
  param :password, String, desc: "mot de passe", required: true
  returns code: 200, desc: "return user token"
  error code: 401, desc: "Unauthorized"
  example <<-JSON
    {
      detail: "Token Example",
    }
  JSON

  def token
    #Mise en œuvre omise
  end

Générer un fichier de définition d'API

$ rails apipie:static_swagger_json

schema_swagger_form_data.json est généré dans doc / apidoc.

2. Gérez les conteneurs de l'interface utilisateur Swagger avec docker-compose

paramètres de composition du menu fixe

docker-compose.yml

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

Lorsque vous démarrez docker et accédez à localhost: 8081, vous pourrez lire la définition de l'API.

Référence: Exécuter Swagger Editor et Swagger UI avec Docker

Ajuster apipie.rb

Puisque la structure du répertoire et le port diffèrent selon le projet, ajustez apipie.rb si nécessaire. Voir aussi la référence Swagger \ -Specific Configuration Parameters pour plus de détails.

apipie.rb

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

N'oubliez pas de générer le document après l'ajustement.

3. Afficher et demander / répondre aux définitions d'API dans l'interface utilisateur Swagger dans l'environnement local

Avec les paramètres actuels, les conteneurs API et Swagger UI sont différents, de sorte que les requêtes / réponses API ne peuvent pas être effectuées. Réglez CORS pour le résoudre.

Paramètres CORS

Ajoutez le gem pour rack \ -cors et ajoutez les paramètres comme indiqué ci-dessous.

Gemfile

gem "rack-cors"

config/application.rb

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

    #Ajoutez ce qui suit
    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 #port d'application
   - localhost:8081 # swagger-port ui

development:
  <<: *default

test:
  <<: *default

production:
  domain:

Après la réécriture, redémarrez le conteneur d'application et vous pourrez faire des demandes à partir de l'interface utilisateur de Swagger.

référence:

• TypeError: Impossible de récupérer dans Swagger \ -UI et mourir
• [Division des paramètres CORS par environnement](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)