Afficher les spécifications de l'API avec Laravel + SwaggerUI + Docker
introduction
Lancez le conteneur Swagger UI avec Docker et affichez les spécifications API de l'API créée avec Laravel.
Chose que tu veux faire
--Je souhaite afficher les spécifications de l'API avec l'interface utilisateur Swagger
Non mentionné dans cet article
- Procédure de développement de l'API Laravel, etc.
Structure du répertoire
.
├── docker-file
│ └── web
│ ├── Dockerfile
│ └── php.ini
├── swagger-docs
│ └── swagger.json
├── volumes
│ └── swagger-api
└── docker-compose.yml
Contenu de chaque fichier
docker-compose.yml Puisque nous nous concentrons cette fois sur swagger-ui, la description de l'élément db est omise.
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 Préparez un fichier vide.
Courir
Commencez par docker-compose.
$ 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
Installation
Installez les bibliothèques requises avec composer. La dernière est la série 3.x, mais il semble qu'elle soit assez différente de la série 2.x que j'ai utilisée auparavant, donc cette fois, j'installerai la dernière version de la série 2.x.
$ composer require zircote/swagger-php:2.0.16
Installation de fichiers php pour Swagger
Créez un fichier php dans le répertoire où vous souhaitez générer le document. Cette fois, placez-le directement sous le répertoire des contrôleurs.
/app/Http/Controllers/swagger.php
<?php
/**
* @SWG\Swagger(
* @SWG\Info(
* version="1.0",
* title="Laravel API Specification",
* ),
* )
*/
Le commentaire pour Swagger est décrit dans Controller
Cette fois, j'ai créé un ProductController avec Get / Post / Put / Delete comme exemple. Le contenu de la méthode est omis.
/app/Http/Controllers/Api/ProductController.php
<?php
....
class ProductController extends Controller
{
/**
* @SWG\Get(
* path="/api/product/{product_id}",
* summary="Acquisition d'informations sur les produits",
* description="Obtenez des informations sur les produits.",
* produces={"application/json"},
* tags={"Product"},
* @SWG\Parameter(
* name="product_id",
* description="ID produit",
* 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="Enregistrement des informations sur le produit",
* description="Enregistrez les informations sur le produit.",
* 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="Code produit"),
* @SWG\Property(property="name", type="string", description="Nom du produit"),
* @SWG\Property(property="price", type="integer", description="Prix de vente"),
* )
* ),
* @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="Mise à jour des informations sur le produit",
* description="Mettez à jour les informations sur le produit.",
* 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="ID produit"),
* @SWG\Property(property="code", type="string", description="Code produit"),
* @SWG\Property(property="name", type="string", description="Nom du produit"),
* @SWG\Property(property="price", type="integer", description="Prix de vente"),
* )
* ),
* @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="Supprimer les informations sur le produit",
* description="Supprimez les informations sur le produit.",
* 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="ID produit"),
* ),
* ),
* @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)
{
....
}
}
génération swagger.json
Utilisez la commande suivante pour générer swagger.json à partir des commentaires décrits.
Le répertoire de sortie après -o. L'emplacement de sortie peut être n'importe où, mais il est spécifié ici car il sera placé dans le répertoire swagger-docs du côté docker à la fin.
$ vendor/bin/swagger app/Http/Controllers/ -o ../../swagger-docs/
Vérifier avec le navigateur
Étant donné que la sortie swagger-docs / swagger.json précédemment est référencée dans docker-compose.yml, vous pouvez vérifier les spécifications de l'API en accédant à l'URL suivante.
http://localhost:8081/
Recommended Posts