Zeigen Sie API-Spezifikationen mit Laravel + SwaggerUI + Docker an
Einführung
Starten Sie den Swagger UI-Container mit Docker und zeigen Sie die API-Spezifikationen der mit Laravel erstellten API an.
Was du machen willst
- Ich möchte API-Spezifikationen mit der Swagger-Benutzeroberfläche anzeigen
In diesem Artikel nicht erwähnt
- Entwicklungsverfahren für die Laravel-API usw.
.
├── docker-file
│ └── web
│ ├── Dockerfile
│ └── php.ini
├── swagger-docs
│ └── swagger.json
├── volumes
│ └── swagger-api
└── docker-compose.yml
docker-compose.yml
docker-compose.yml
version: '3'
services:
web:
container_name: web
build: ./docker-file/web/
ports:
- 8080:80
volumes:
- ./volumes/swagger-api:/var/www/html/swagger-api
db:
container_name: mysql
....
swagger:
container_name: swagger-ui
image: swaggerapi/swagger-ui
volumes:
- ./swagger-docs/swagger.json:/usr/share/nginx/html/swagger.json
environment:
API_URL: swagger.json
ports:
- "8081:8080"
docker-file/web/Dockerfile
FROM php:7.4-apache
COPY ./php.ini /usr/local/etc/php/
RUN apt-get update \
&& apt-get install --no-install-recommends -y git curl wget sudo libfreetype6-dev libjpeg62-turbo-dev libmcrypt-dev libmcrypt-dev libxml2-dev libpq-dev libzip-dev libpq5 postgresql-client default-mysql-client libicu-dev libonig-dev \
&& mv /etc/apache2/mods-available/rewrite.load /etc/apache2/mods-enabled \
&& docker-php-ext-configure gd --with-freetype=/usr/include/ --with-jpeg=/usr/include/ \
&& docker-php-ext-install -j$(nproc) zip gd xml pdo pdo_mysql mysqli soap intl \
&& rm -r /var/lib/apt/lists/*
RUN /bin/sh -c a2enmod rewrite
docker-file/web/php.ini
php.ini
[Core]
display_errors = On
error_reporting = E_ALL
error_log = /var/log/apache2/error.log
log_errors = On
[Date]
date.timezone = 'Asia/Tokyo'
[mbstring]
mbstring.language = Japanese
mbstring.internal_encoding = auto
mbstring.http_input = auto
mbstring.http_output = auto
mbsting.encoding_translation = Off
mbstring.detect_order = auto
swagger-docs/swagger.json
$ docker-compose up -d
Creating network "swagger-ui-docker_default" with the default driver
Creating swagger-ui ... done
Creating mysql ... done
Creating web ... done
Swagger
Inhalt jeder Datei Da wir uns diesmal auf swagger-ui konzentrieren, wird die Beschreibung des db-Elements weggelassen. Halten Sie eine leere Datei bereit. Führen Sie Start mit Docker-Compose aus. Installation
Installieren Sie die erforderlichen Bibliotheken mit Composer. Die neueste ist die 3.x-Serie, aber es scheint, dass sie sich stark von der 2.x-Serie unterscheidet, die ich zuvor verwendet habe. Deshalb werde ich dieses Mal die neueste Version der 2.x-Serie installieren.
$ composer require zircote/swagger-php:2.0.16
Installation der PHP-Datei für Swagger
Erstellen Sie eine PHP-Datei in dem Verzeichnis, in dem Sie das Dokument generieren möchten. Platzieren Sie es diesmal direkt im Verzeichnis Controller.
/app/Http/Controllers/swagger.php
<?php
/**
* @SWG\Swagger(
* @SWG\Info(
* version="1.0",
* title="Laravel API Specification",
* ),
* )
*/
Kommentar für Swagger ist in Controller beschrieben
Dieses Mal habe ich einen ProductController mit Get / Post / Put / Delete als Beispiel erstellt. Der Inhalt der Methode wird weggelassen.
/app/Http/Controllers/Api/ProductController.php
<?php
....
class ProductController extends Controller
{
/**
* @SWG\Get(
* path="/api/product/{product_id}",
* summary="Erfassung von Produktinformationen",
* description="Produktinformationen abrufen.",
* produces={"application/json"},
* tags={"Product"},
* @SWG\Parameter(
* name="product_id",
* description="Produkt ID",
* in="path",
* required=true,
* type="integer"
* ),
* @SWG\Response(
* response=200,
* description="Success",
* ),
* @SWG\Response(
* response=400,
* description="Bad Request error",
* ),
* @SWG\Response(
* response=401,
* description="Unauthorized error"
* ),
* )
*/
public function show($product_id)
{
....
}
/**
* @SWG\Post(
* path="/api/product",
* summary="Registrierung von Produktinformationen",
* description="Registrieren Sie die Produktinformationen.",
* produces={"application/json"},
* tags={"Product"},
* @SWG\Parameter(
* in="body",
* name="Product",
* description="List of product object",
* @SWG\Schema(
* type="object",
* @SWG\Property(property="code", type="string", description="Produktcode"),
* @SWG\Property(property="name", type="string", description="Produktname"),
* @SWG\Property(property="price", type="integer", description="Verkaufspreis"),
* )
* ),
* @SWG\Response(
* response=200,
* description="Success",
* ),
* @SWG\Response(
* response=400,
* description="Bad Request error",
* ),
* @SWG\Response(
* response=401,
* description="Unauthorized error"
* ),
* )
*/
public function store(Request $request)
{
....
}
/**
* @SWG\Put(
* path="/api/product",
* summary="Aktualisierung der Produktinformationen",
* description="Aktualisieren Sie die Produktinformationen.",
* produces={"application/json"},
* tags={"Product"},
* @SWG\Parameter(
* in="body",
* name="Product",
* description="List of product object",
* @SWG\Schema(
* type="object",
* @SWG\Property(property="product_id", type="integer", description="Produkt ID"),
* @SWG\Property(property="code", type="string", description="Produktcode"),
* @SWG\Property(property="name", type="string", description="Produktname"),
* @SWG\Property(property="price", type="integer", description="Verkaufspreis"),
* )
* ),
* @SWG\Response(
* response=200,
* description="Success",
* ),
* @SWG\Response(
* response=400,
* description="Bad Request error",
* ),
* @SWG\Response(
* response=401,
* description="Unauthorized error"
* ),
* )
*/
public function update(Request $request)
{
....
}
/**
* @SWG\Delete(
* path="/api/product",
* summary="Produktinformationen löschen",
* description="Löschen Sie die Produktinformationen.",
* produces={"application/json"},
* tags={"Product"},
* @SWG\Parameter(
* in="body",
* name="Product",
* description="List of product object",
* @SWG\Schema(
* type="object",
* @SWG\Property(property="product_id", type="integer", description="Produkt ID"),
* ),
* ),
* @SWG\Response(
* response=200,
* description="Success",
* ),
* @SWG\Response(
* response=400,
* description="Bad Request error",
* ),
* @SWG\Response(
* response=401,
* description="Unauthorized error"
* ),
* )
*/
public function destroy(Request $request)
{
....
}
}
swagger.json Generation
Verwenden Sie den folgenden Befehl, um swagger.json aus den beschriebenen Kommentaren zu generieren.
Das Ausgabeverzeichnis nach -o. Der Ausgabeort kann sich an einer beliebigen Stelle befinden, wird jedoch hier angegeben, da er am Ende im Verzeichnis swagger-docs auf der Docker-Seite abgelegt wird.
$ vendor/bin/swagger app/Http/Controllers/ -o ../../swagger-docs/
Überprüfen Sie mit dem Browser
Da ich versuche, auf die Ausgabe von swagger-docs / swagger.json früher in docker-compose.yml zu verweisen, können Sie die API-Spezifikationen überprüfen, indem Sie auf die folgende URL zugreifen.
http://localhost:8081/
Recommended Posts