[RUBY] Erstellen Sie mit Docker eine Umgebung für "API-Entwicklung + API-Überprüfung mithilfe der Swagger-Benutzeroberfläche"

Mit Swagger können Sie die REST-API-Spezifikationen dokumentieren. In Swagger heißt die Datei, die die REST-API-Spezifikationen dokumentiert, Swagger Spec.

Swagger UI ist ein Tool, das statische Seiten generiert, die Swagger Spec-Informationen widerspiegeln. Die Swagger-Benutzeroberfläche visualisiert nicht nur Swagger-Spezifikationsinformationen, sondern bietet auch die Möglichkeit, REST-APIs über den Bildschirm auszuführen.

Dieses Mal werden wir das Verfahren zum Erstellen einer Docker-Umgebung vorstellen, mit der Sie eine Reihe von Aufgaben ausführen können, z. B. "Dokumentieren der in der Entwicklung befindlichen API mit Swagger Spec → Überprüfen der API-Anforderung auf dem Swagger-UI-Bildschirm, der die Swagger Spec-Informationen widerspiegelt".

Informationen zur Docker-Umgebung, die dieses Mal erstellt wurde

Die Spezifikationen sind wie folgt.

• Die Umgebung kann nur durch Docker-Compose vorbereitet werden
• Der Bildschirm der Swagger-Benutzeroberfläche wird mit "/ swagger -ui" angezeigt.
• Verwenden Sie bis auf "/ swagger-ui" Endpunkte für die API
• Nach dem Bearbeiten der Swagger-Spezifikation werden beim erneuten Laden die Änderungen in der Swagger-Benutzeroberfläche berücksichtigt. --Erstellen Sie die API im API-Modus von Ruby on Rails --DB verwendet MySQL

Durch die Verwendung von nginx als Reverse-Proxy können Sie die API-Entwicklungsumgebung mit der Swagger-Benutzeroberfläche kombinieren. Die Figur ist wie folgt.

Die verschiedenen Versionen, die dieses Mal verwendet werden, sind wie folgt.

• Ruby on Rails: 6.0.3.2
• Ruby: 2.7.1
• MySQL: 8.0.21
• nginx: 1.19.3

Erstellen Sie eine API-Entwicklungsumgebung in Docker

API-Entwicklung im Rails-API-Modus unter Bezugnahme auf im API-Modus erstellte Konstruktionsprozedur für die Rails 6 x MySQL 8 Docker-Umgebung Erstellen Sie eine Umgebung.

Dockerfile und docker-compose.yml lauten wie folgt.

Dockerfile

FROM ruby:2.7.1

#Arbeitsverzeichnis/rails_api_Als Prahlerei bezeichnet
WORKDIR /rails_api_swagger

#Kopieren Sie die lokale Gemfile nach Dokcer
COPY Gemfile* /rails_api_swagger/

# /rails_api_Bundle-Installation im Swagger-Verzeichnis
RUN bundle install

docker-compose.yml

version: '3'
services:
  api: #Container von Ruby on Rails gestartet
    build: .
    ports:
      - '3000:3000' #Machen Sie es auf Port 3000 von localhost zugänglich
    volumes:
      - .:/rails_api_swagger #Synchronisierung von Anwendungsdateien
    depends_on:
      - db
    command: ["./wait-for-it.sh", "db:3306", "--", "./start.sh"]
  db: #Container, den MySQL startet
    image: mysql:8.0.21
    volumes:
      - mysql_data:/var/lib/mysql #Datenpersistenz
      - ./docker-entrypoint-initdb.d:/docker-entrypoint-initdb.d
    command: --default-authentication-plugin=mysql_native_password #Stellen Sie die Authentifizierungsmethode auf 8 Serien oder früher ein.
    environment:
      MYSQL_USER: 'webuser'
      MYSQL_PASSWORD: 'webpass'
      MYSQL_ROOT_PASSWORD: 'pass'
      MYSQL_DATABASE: 'rails_api_swagger_development'
volumes:
  mysql_data: #Registrierung des Datenvolumens

** Der Rails-API-Modus schließt die Möglichkeit aus, statische Seiten zu generieren, sodass Sie die Swagger-Benutzeroberfläche nicht direkt in Ihre Rails-Anwendung einbetten können **. Wenn Sie diese Methode verwenden, können Sie die Swagger-Benutzeroberfläche auch im API-Modus verwenden. Ich kann es schaffen

Erstellen Sie eine Beispiel-API.

#Starten Sie den Container im Hintergrund
$ docker-compose up -d

#Erstellen Sie gemeinsam Funktionen (Modelle, Ansichten, Controller), um Ereignisse zu betreiben
$ docker-compose exec api rails g scaffold event title:string

#Ereignistabelle erstellen
$ docker-compose exec api rails db:migrate

#Erstellen Sie eine Aufzeichnung von Ereignissen in der Rails-Konsole
$ docker-compose exec api rails c
> event = Event.new(title: 'Beispielereignis')
> event.save

Es ist in Ordnung, wenn Sie auf "localhost: 3000 / events" zugreifen und die folgende Antwort erhalten.

Richten Sie einen Reverse-Proxy ein, damit Sie über nginx auf die API zugreifen können

Richten Sie den Reverse-Proxy so ein, dass Sie über nginx auf Ihre Rails-Anwendung zugreifen können.

default.conf

server {
  listen 80;
  server_name  localhost;

  # "/"Verarbeitung, wenn Zugriff auf
  location / {
    proxy_set_header Host localhost; #Setzen Sie den Zugriffsquellenhost auf localhost
    proxy_pass http://api:3000; #Senden Sie eine Anfrage an Port 3000 des API-Containers
  }
}

Die Nginx-Konfigurationsdatei lautet "/ etc / nginx / nginx.conf". Wie Sie der Beschreibung "include /etc/nginx/conf.d / *. Conf;" in der Einstellungsdatei entnehmen können, wird sie in der Einstellungsdatei unter "/ etc / nginx / conf.d" als ".conf" bezeichnet. Die Erweiterungseinstellungen werden ebenfalls geladen.

Mit anderen Worten, der Nginx-Container kann als Reverse-Proxy verwendet werden, indem die diesmal erstellte Konfigurationsdatei unter "/ etc / nginx / conf.d" abgelegt wird.

Fügen Sie den nginx-Container zu docker-compose.yml hinzu.

docker-compose.yml

services:
  api:
    (Abkürzung)
  db:
    (Abkürzung)
  nginx:
    image: nginx:1.19.3
    ports:
      - '80:80'
    command: [nginx-debug, '-g', 'daemon off;']
    volumes:
      - ./nginx/conf.d/default.conf:/etc/nginx/conf.d/default.conf
    depends_on:
      - api
volumes:
  mysql_data:

[nginx-debug, '- g', 'daemon off;'] ist die Startmethode im Debug-Modus. [^ nginx-debugmode]

Docker-Image von swagger-ui verwendet ebenfalls nginx, aber include / etc / in nginx.confEs gibt keine Beschreibung von nginx / conf.d / *. Conf;. Beachten Sie daher, dass dieser Ansatz nicht funktioniert, wenn Sie das Docker-Image von ** swagger-ui ** verwenden.

Greifen Sie nach dem Starten des Containers auf localhost: 80 / events zu und erhalten Sie die folgende Antwort.

Integrieren Sie die Swagger-Benutzeroberfläche in Nginx

Wenn Sie auf / swagger-ui zugreifen, wird die Swagger-Benutzeroberfläche in nginx integriert, sodass der Bildschirm der Swagger-Benutzeroberfläche angezeigt wird.

Der Swagger-UI-Bildschirm besteht aus swagger-ui / dist.

Die Swagger-Benutzeroberfläche wird in Nginx eingebettet, indem die Dateien unter "dist" lokal kopiert und im Nginx-Container gebunden werden.

Sie können alle Dateien unter "dist" kopieren, aber mit unpkg können Sie nur "index.html" und den Swagger-UI-Bildschirm kopieren. Kann erstellt werden. [^ swagger-ui-installation]

index.html

<!-- HTML for static distribution bundle build -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
-   <link rel="stylesheet" type="text/css" href="./swagger-ui.css" >
+   <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@3/swagger-ui.css" >
    <style>
      html
      {
        box-sizing: border-box;
        overflow: -moz-scrollbars-vertical;
        overflow-y: scroll;
      }

      *,
      *:before,
      *:after
      {
        box-sizing: inherit;
      }

      body
      {
        margin:0;
        background: #fafafa;
      }
    </style>
  </head>

  <body>
    <div id="swagger-ui"></div>

-   <script src="./swagger-ui-bundle.js" charset="UTF-8"> </script>
+   <script src="https://unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js" charset="UTF-8"> </script>
-   <script src="./swagger-ui-standalone-preset.js" charset="UTF-8"> </script>
+   <script src="https://unpkg.com/swagger-ui-dist@3/swagger-ui-standalone-preset.js" charset="UTF-8"> </script>

    <script>
    window.onload = function() {
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
        url: "https://petstore.swagger.io/v2/swagger.json",
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
      // End Swagger UI call region

      window.ui = ui
    }
  </script>
  </body>
</html>

Ändern Sie docker-compose.yml und platzieren Sie die erstellte index.html unter / usr / share / nginx / html, dem öffentlichen Standardverzeichnis von nginx.

docker-compose.yml

services:![Screenshot 2020-10-25 18.23.07.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/140792/22cf7096-e237-7c2e-3aa5-0959d4776657.png)

  api:
    (Abkürzung)
  db:
    (Abkürzung)
  nginx:
    image: nginx:1.19.3
    ports:
      - '80:80'
    command: [nginx-debug, '-g', 'daemon off;']
    volumes:
      - ./nginx/conf.d/default.conf:/etc/nginx/conf.d/default.conf
+     - ./nginx/html/swagger-ui:/usr/share/nginx/html/swagger-ui
    depends_on:
      - api
volumes:
  mysql_data:

Fügen Sie Nginx-Einstellungen hinzu, damit "index.html" angezeigt wird, wenn Sie auf "/ swagger-ui" zugreifen.

default.conf

server {
  listen 80;
  server_name  localhost;

  location / {
    proxy_set_header Host localhost;
    proxy_pass http://api:3000;
  }

  # "swagger-ui"Verarbeitung, wenn Zugriff auf
  location /swagger-ui {
    alias /usr/share/nginx/html/swagger-ui;
  }
}

Rufen Sie nach dem Starten des Containers `` localhost: 80 / swagger-ui` auf und es ist OK, wenn der folgende Bildschirm angezeigt wird.

Stellen Sie sicher, dass die lokale Swagger-Spezifikation auf der Swagger-Benutzeroberfläche angezeigt wird

Sie können die referenzierte Swagger-Spezifikation ändern, indem Sie die URL in der Swagger-Benutzeroberfläche ändern.

Ändern Sie es, um auf die lokale Swagger-Spezifikation zu verweisen.

index.html

- url: "https://petstore.swagger.io/v2/swagger.json",
+ url: "./api.yml",

Mit den oben genannten Änderungen wird der Inhalt von . / Nginx / html / swagger-ui / api.yml in der lokalen Umgebung in der Swagger-Benutzeroberfläche angezeigt.

Das Verzeichnis . / Nginx / html / swagger-ui / ist bindgebunden. Wenn Sie also die Swagger-Spezifikation lokal bearbeiten und dann neu laden, werden die Änderungen in der Swagger-Benutzeroberfläche des Containers angezeigt. ** ** **

Die Swagger-Spezifikation, die das als Beispiel erstellte GET / events ausführt, lautet wie folgt.

api.yml

openapi: 3.0.2
info:
  title:Beispiel-API
  version: 1.0.0
servers:
  - url: http://localhost:3000
tags:
  - name:Veranstaltung
paths:
  /events:
    get:
      tags:
        -Veranstaltung
      description:Ereignisliste abrufen
      responses:
        200:
          description:Erfolg
          content:
            application/json:
              schema:
                type: array
                description:Array von Ereignissen
                items:
                  $ref: "#/components/schemas/Event"
components:
  schemas:
    Event:
      type: object
      properties:
        id:
          description: ID
          type: integer
          format: int64
          example: 1
        title:
          description:Titel
          type: string
          example:Beispielereignis
        created_at:
          description:Erstellungsdatum
          type: string
          format: date-time
          example: 2020-04-01 10:00
        updated_at:
          description:Aktualisierungsdatum
          type: string
          format: date-time
          example: 2020-04-01 10:00

Nach dem Starten des Containers ist es in Ordnung, wenn der folgende Bildschirm angezeigt wird.

Stellen Sie CORS ein

Die Swagger-Benutzeroberfläche läuft auf "localhost: 80" und die API läuft auf "localhost: 3000". Wenn Sie in diesem Status eine Anforderung von der Swagger-Benutzeroberfläche an die API senden, überspannt sie den Ursprung. Daher wurde der Zugriff zum Abrufen von "http: // localhost: 3000 / events" von origin "http: // localhost" durch die CORS-Richtlinie blockiert Fehler tritt auf.

Richten Sie CORS so ein, dass API-Anforderungen über die Swagger-Benutzeroberfläche gesendet werden können. Verwenden Sie dieses Mal Rack-Cors, um CORS festzulegen.

Gemfile

gem 'rack-cors'

config/initializers/cors.rb

Rails.application.config.middleware.insert_before 0, Rack::Cors do
  unless Rails.env.production?
    allow do
      origins(['localhost', /localhost:\d+\Z/])

      resource '*',
        headers: :any,
        methods: [:get, :post, :put, :patch, :delete, :options, :head]
    end
  end
end

Nach dem Starten des Containers ist es in Ordnung, wenn die Anforderung normal zurückgegeben wird.

Referenz: Swagger Spec, die CRUD-Operationen ausführt

• GET /events
• POST /events
• GET /events/{id}
• PATCH /events/{id}
• DELETE /events/{id}

Die Swagger-Spezifikation für die oben genannten Endpunkte lautet:

api.yml

openapi: 3.0.2
info:
  title:Beispiel-API
  version: 1.0.0
servers:
  - url: http://localhost:3000
tags:
  - name:Veranstaltung
paths:
  /events:
    get:
      tags:
        -Veranstaltung
      description:Ereignisliste abrufen
      responses:
        200:
          description:Erfolg
          content:
            application/json:
              schema:
                type: array
                description:Array von Ereignissen
                items:
                  $ref: "#/components/schemas/Event"
    post:
      tags:
        -Veranstaltung
      description:Veranstaltungsanmeldung
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  example:Beispielereignis
      responses:
        201:
          description:Erstellen
  /events/{event_id}:
    get:
      tags:
        -Veranstaltung
      description:Veranstaltungsdetails
      parameters:
        - name: event_id
          in: path
          description:Ereignis-ID
          required: true
          schema:
            type: integer
            format: int64
            example: 1
      responses:
        200:
          description:Erfolg
          content:
            application/json:
              schema:
                type: object
                $ref: "#/components/schemas/Event"
        404:
          description: event not found
    patch:
      tags:
        -Veranstaltung
      description:Ereignisaktualisierung
      parameters:
        - name: event_id
          in: path
          description: id
          required: true
          schema:
            type: integer
            format: int64
          example: 1
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  example:Beispielereignis
      responses:
        200:
          description:Erfolg
          content:
            application/json:
              schema:
                type: object
                properties:
                  activity:
                    $ref: "#/components/schemas/Event"
    delete:
      tags:
        -Veranstaltung
      description:Ereignis löschen
      parameters:
        - name: event_id
          in: path
          description: id
          required: true
          schema:
            type: integer
            format: int64
            example: 1
      responses:
        204:
          description: No Content
components:
  schemas:
    Event:
      type: object
      properties:
        id:
          description: ID
          type: integer
          format: int64
          example: 1
        title:
          description:Titel
          type: string
          example:Beispielereignis
        created_at:
          description:Erstellungsdatum
          type: string
          format: date-time
          example: 2020-04-01 10:00
        updated_at:
          description:Aktualisierungsdatum
          type: string
          format: date-time
          example: 2020-04-01 10:00

Der Bildschirm sieht folgendermaßen aus:

Zusammenfassung

Damit ist die Einführung des Verfahrens zum Erstellen einer Entwicklungsumgebung abgeschlossen, in die die API und die Swagger-Benutzeroberfläche integriert sind.

• Kombinieren Sie die Benutzeroberfläche und API von Swagger mithilfe von nginx --Erstellen Sie unter "/etc/nginx/conf.d" Reverse-Proxy-Einstellungen für nginx. --CORS-Einstellungen sind erforderlich, wenn Anfragen über Ursprünge hinweg gestellt werden
• Ändern Sie die URL von index.html, um Ihre eigene Swagger-Spezifikation in der Swagger-Benutzeroberfläche wiederzugeben

Ich mache Twitter (@ nishina555). Ich hoffe du folgst mir!