Add Swagger API documentation and proxy routing.

Added Swagger as a new service in the docker-compose file for generating the API documentation. The new API documentation is provided via an OpenAPI file located at `public/swagger.json`. Changes in routing were done to handle /api-docs requests and redirect them to the running Swagger UI instance. This will make API easier to understand and debug.
This commit is contained in:
Leonid Nikitin 2023-08-23 01:02:56 +06:00
parent 742b0feaf0
commit 9bfd3fef1a
Signed by: kor-elf
GPG Key ID: 7DE8F80C5CEC2C0D
3 changed files with 245 additions and 2 deletions

View File

@ -40,6 +40,15 @@ services:
volumes:
- ./docker/dev/db:/var/lib/mysql
- ./docker/dev/my.cnf:/etc/mysql/conf.d/my.cnf
swagger:
image: swaggerapi/swagger-ui
environment:
URLS: "[ { url: '/swagger.json', name: '/swagger.json' } ]"
BASE_URL: /api-docs
ports:
- "8080"
# volumes:
# - ./docker/swagger:/swagger
adminer:
image: adminer
#restart: always

View File

@ -7,10 +7,18 @@ server {
root /var/www/html/public;
location / {
location /api-docs {
proxy_pass http://swagger:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;
}
location / {
# try to serve file directly, fallback to index.php
try_files $uri /index.php$is_args$args;
}
}
location ~ ^/index\.php(/|$) {
fastcgi_pass app:9000;

226
public/swagger.json Normal file
View File

@ -0,0 +1,226 @@
{
"openapi": "3.0.3",
"info": {
"title": "Captcha service - API",
"description": "API Documentation.",
"version": "1.0.0"
},
"servers": [
{
"url": "/api/v1"
}
],
"tags": [
{
"name": "captcha",
"description": "Operations about captcha"
}
],
"paths": {
"/captcha": {
"get": {
"tags": [
"captcha"
],
"summary": "Captcha generation",
"description": "",
"operationId": "captchaGeneration",
"parameters": [
{
"name": "public_token",
"in": "header",
"description": "Public token for captcha generation",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Captcha"
}
}
}
}
},
"403": {
"description": "Invalid public token value"
}
}
},
"post": {
"tags": [
"captcha"
],
"summary": "Checking captcha",
"description": "",
"operationId": "captchaChecking",
"parameters": [
{
"name": "public_token",
"in": "header",
"description": "Public token for captcha generation",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CaptchaChecking"
}
}
}
}
},
"responses": {
"200": {
"description": "successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CaptchaVerification"
}
}
}
}
},
"403": {
"description": "Invalid public token value"
}
}
}
},
"/captcha/{captcha_key}": {
"get": {
"tags": [
"captcha"
],
"summary": "Verification Information",
"description": "",
"operationId": "CaptchaKeyInfo",
"parameters": [
{
"name": "private_token",
"in": "header",
"description": "Private token for captcha verification",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "captcha_key",
"in": "path",
"description": "The key that we received when generating the captcha",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CaptchaKeyInfo"
}
}
}
}
},
"403": {
"description": "Invalid private token value"
},
"404": {
"description": "Captcha key not found"
}
}
}
}
},
"components": {
"schemas": {
"Captcha": {
"type": "object",
"properties": {
"image_base64": {
"type": "string",
"format": "byte"
},
"image_text_base64": {
"type": "string",
"format": "byte"
},
"captcha_key": {
"type": "string"
}
},
"required": [
"image_base64", "image_text_base64", "captcha_key"
]
},
"CaptchaVerification": {
"type": "object",
"properties": {
"status": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"status", "message"
]
},
"CaptchaChecking": {
"type": "object",
"properties": {
"captcha_key": {
"type": "string"
},
"verification": {
"type": "array",
"example": [{"x": 10, "y": 20}, {"x": 30, "y": 30}, {"x": 60, "y": 50}]
}
},
"required": [
"captcha_key", "verification"
]
},
"CaptchaKeyInfo": {
"type": "object",
"properties": {
"status": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"status", "message"
]
}
}
}
}