README

描述

从模型自动生成Swagger-PHP注释。使用路由、表单请求和少量注解自动生成Swagger-PHP注释。

安装

composer require --dev suzunone/l-auto-comment-for-php-swagger

php artisan vendor:publish --provider="AutoCommentForPHPSwagger\LAutoCommentForPHPSwaggerServiceProvider" --tag=config

使用

openapi:info-comment
- 创建OA\Info文件
openapi:security-comment
- 创建安全设置文件
openapi:create-model-to-schema
- 为模型创建Swagger-PHP模式文件
openapi:file-to-annotation
- 从yaml或json创建注释定义
openapi:swagger-comment
- 自动为Swagger-PHP生成注释

openapi注解

可以使用小的注解代替非常庞大的Swagger-PHP格式注释。

在控制器的每个方法中写入，从FormRequest和路由自动生成Swagger-PHP风格的注解。

FormRequest

@property {TYPE} {VARIABLE NAME} {DESCRIPTION}
@property-read {TYPE} {VARIABLE NAME} {DESCRIPTION}

描述请求中要接收的参数，与PHP Doc中的属性相同
@openapi-in {REQUEST IN} {VARIABLE NAME} 指定in字段的参数位置。如未指定，则in="query"。
@openapi-content {MIME} {FORMAT} {DESCRIPTION} 当使用request()->getContent()时，可以指定内容。可以指定多个，但只有一个描述会被使用。

控制器

@openapi

描述是否包含openapi:swagger-comment目标。
@openapi-tags

描述API标签。

可以有多个。

如未指定，将自动从控制器名称等生成。
@openapi-response {HTTP STATUS} {RESPONSE SCHEMA} {DESCRIPTION}

可以描述API的响应。

指定预准备的模式。

模式可以是嵌套的。

可以通过更改HTTP STATUS进行多个条目。
@openapi-response-type {HTTP STATUS} {RESPONSE TYPE} {CONTENT TYPE}

可以指定响应类型。可以选择json xml媒体类型，如果选择媒体类型，可以指定内容类型。如果有多个响应类型，可以列出多个响应。如未指定，则使用json。
@openapi-ignore-session-cookie
@openapi-session-cookie

切换是否使用会话cookie。
@openapi-ignore-csrf-header
@openapi-csrf-header

切换是否使用CSRF头部。
@openapi-security {securityScheme} {SCOPES(comma-separated)}
@openapi-security {Security setting json}

要使用的安全设置

一个非常简单的例子

    /**
     * Here is the description of the API
     *
     * @openapi
     * @openapi-tags TAG-A
     * @openapi-tags TAG-B
     * @openapi-response 200 #/components/schemas/ExampleModel Success
     * @openapi-response 400 #/components/schemas/Error Bad Request
     * @openapi-response 403 #/components/schemas/Error Forbidden
     * @openapi-response 404 #/components/schemas/Error Not Found
     * @openapi-response 405 #/components/schemas/Error Invalid Input
     */

/**
 * @OA\Get(
 *   tags={"TAG-A", "TAG-B"},
 *   operationId="exampleIndex",
 *   path="/api/example",
 *   description="Here is the description of the API",
 *
 *   @OA\Response(
 *     response="200",
 *     description="Success",
 *     @OA\JsonContent(ref="#/components/schemas/ExampleModel")
 *   ),
 *   @OA\Response(
 *     response="400",
 *     description="Bad Request",
 *     @OA\JsonContent(ref="#/components/schemas/CommonError")
 *   ),
 *   @OA\Response(
 *     response="403",
 *     description="Forbidden",
 *     @OA\JsonContent(ref="#/components/schemas/CommonError")
 *   ),
 *   @OA\Response(
 *     response="404",
 *     description="Not Found",
 *     @OA\JsonContent(ref="#/components/schemas/CommonError")
 *   ),
 *   @OA\Response(
 *     response="405",
 *     description="Invalid Input",
 *     @OA\JsonContent(ref="#/components/schemas/CommonError")
 *   ),
 * )
*/

Nest Response Usage

单层嵌套

@openapi-response 200 #/components/schemas/ExampleModel&foo_model=#/components/schemas/FooModel&bar_mode=#/components/schemas/BarModel

深层嵌套

@openapi-response 200 #/components/schemas/ExampleModel&foo_model[#/components/schemas/FooModel]&foo_model[bar_mode]=#/components/schemas/BarModel

自动生成的Model的模式

Create{ModelName}

排除自增列。除了对其他模型的引用。

Create{ModelName}WithRelation

排除自增列。包含对其他模型的引用。

{ModelName}

包含自增列。除了对其他模型的引用。

{ModelName}WithRelation

包含自增列。包含对其他模型的引用。

{ModelName}Many

模型数组。除对其他模型的引用外。

{ModelName}WithRelationMany

模型数组。包括对其他模型的引用。

{ModelName}Paginate

模型分页。除对其他模型的引用外。

{ModelName}WithRelationPaginate

模型分页。包括对其他模型的引用。

suizunone / l-auto-comment-for-php-swagger

维护者

详细信息