一、Swagger-php 注解怎么写？
（一）参数示例
官方示例
<?php
namespace OpenApi\Examples\ExampleObject;
use OpenApi\Annotations as OA;
/**
* @OA\Tag(
* name="user",
* description="User related operations"
* )
* @OA\Info(
* version="1.0",
* title="Example for response examples value",
* description="Example info",
* @OA\Contact(name="Swagger API Team")
* )
* @OA\Server(
* url="https://example.localhost",
* description="API server"
* )
*/
class OpenApiSpec
{
}
/**
* @OA\Put(
* path="/users/{id}",
* summary="Updates a user",
* description="Updates a user",
* operationId="updateUser",
* tags={"user"},
* @OA\Parameter(
* description="Parameter with mutliple examples",
* in="path",
* name="id",
* required=true,
* @OA\Schema(type="string"),
* @OA\Examples(example="int", value="1", summary="An int value."),
* @OA\Examples(example="uuid", value="0006faf6-7a61-426c-9034-579f2cfcfa83", summary="An UUID value."),
* ),
* @OA\Response(
* response=200,
* description="OK"
* )
* )
*/
class UserUpdateEndpoint
{
}
/**
* @OA\Post(
* path="/users",
* summary="Adds a new user - with oneOf examples",
* description="Adds a new user",
* operationId="addUser",
* tags={"user"},
* @OA\RequestBody(
* @OA\MediaType(
* mediaType="application/json",
* @OA\Schema(
* @OA\Property(
* property="id",
* type="string"
* ),
* @OA\Property(
* property="name",
* type="string"
* ),
* @OA\Property(
* property="phone",
* oneOf={
* @OA\Schema(type="string"),
* @OA\Schema(type="integer"),
* }
* ),
* example={"id": "a3fb6", "name": "Jessica Smith", "phone": 12345678}
* )
* )
* ),
* @OA\Response(
* response=200,
* description="OK",
* @OA\JsonContent(
* oneOf={
* @OA\Schema(ref="#/components/schemas/Result"),
* @OA\Schema(type="boolean")
* },
* @OA\Examples(example="result", value={"success": true}, summary="An result object."),
* @OA\Examples(example="bool", value=false, summary="A boolean value."),
* )
* )
* )
*/
class UserAddEndpoint
{
}
/**
* @OA\Schema(
* schema="Result",
* title="Sample schema for using references",
* @OA\Property(
* property="status",
* type="string"
* ),
* @OA\Property(
* property="error",
* type="string"
* )
* )
*/
class ResultSchema
{
}
（1） 参数示例：
/**
* //声明API版本信息
* @OA\Info(
* title="Live_client_server",
* description="直播客户端系统"
* )
* //声明服务器信息
* @OA\Server(
* url=https://localhost:8080,
* description="这是描述"
* )
*/
class OpenApiSpec
{
}
/**
* //参数描述
* @OA\post(
* path="/online_user_total",
* operationId="yanfa",
* tags={"成员"},
* summary="获取在线成员",
* description="这是描述",
* @OA\Parameter(
* name="price",
* description="价格",
* type="number",
* in="body",
//json=boby query=query x-www-form-urlencoded=formData
* required=true,
* minimum=0.01,
* maximum=100,
* example=0.01
* ),
* @OA\Parameter(
* name="mark",
* description="备注",
* type="string",
* in="body",
* required=true,
* minLength=1,
* maxLength=200,
* example="备注"
* ),
* @OA\Parameter(
* name="is_elive",
* description="是否xx 是-true 否-false",
* type="boolean",
* in="body",
* required=true,
* enum={true,false},
* example=true
* ),
* @OA\Response(
* response=200,
* description="获取成功",
* @OA\JsonContent(type="object",
* @OA\Property(property="code",type="integer"),
* @OA\Property(property="msg",type="string"),
* @OA\Property(property="data", type="array",
* @OA\Items(type="object",
* @OA\Property(property="user_id", type="string"),
* @OA\Property(property="user_name", type="string"),
* @OA\Property(property="user_from", type="integer"),
* ),
* ),
* ),
* ),
* @OA\Response(response=401, description="Unauthorized"),
* @OA\Response(response=404, description="Not Found"),
* )
*
*
*/
（二） 参数释义：
（1） @OA\Info 声明API版本信息
| 字段名称 |
类型 |
描述 |
| version |
string |
需要 Api版本信息。 |
| title |
string |
需要 API的标题。 |
| description |
string |
参数的简要说明 |
（2） @OA\Server 声明服务器信息
| 字段名称 |
类型 |
描述 |
| url |
string |
Api服务器地址。 |
| description |
string |
Api服务器描述 |
| variables |
string |
联系人/组织的邮箱 |
（3） @OA\Post、Get、Put、Delete 参数描述
| 字段名称 |
类型 |
描述 |
| tags |
string |
接口分组名称。 |
| path |
string |
需要。接口请求地址。 |
| summary |
string |
接口名称。 |
| description |
string |
接口详情描述，接口展开描述接口功能或样例。 |
| schemes |
string |
协议http”，“https，可以为列表 |
@OA\Parameter 参数说明
| 字段名称 |
类型 |
描述 |
| name |
string |
需要。参数的名称。参数名称区分大小写。 |
| in |
string |
需要。参数的位置。可能的值是“query”，“header”，“path”，“formData”或“body”。 |
| description |
string |
参数的简要说明。这可能包含使用的例子。 |
| type |
string |
参数的类型。取值权限：“string”，“number”，“integer”，“boolean”，“array”，“file”。 |
| required |
boolean |
确定此参数是否是必需的。其默认值是false。 |
其他属性详解
最大最小值 minimum:0.01,maximum:100
最大最小长度 minLength=1,maxLength=200
枚举值 enum={"A","B","C"}
示例 example=1
默认值(选填) default=1
（4）@OA\Response 参数描述
| 字段名称 |
类型 |
描述 |
| description |
string |
必填 响应的简短描述 |
| schema |
模式对象 |
响应结构的定义。它可以是一个基元，一个数组或一个对象。如果此字段不存在，则表示没有内容作为响应的一部分返回 |
| headers |
标题对象 |
与响应一起发送的标题列表。 |
| examples |
示例对象 |
响应消息的一个例子。 |
（5）@OA\SecurityScheme 鉴权
普通apiKey鉴权
/**
* @OA\SecurityScheme(
* type="apiKey",
* description="全局添加API Token鉴权",
* name="authorization",
* in="header",
* securityScheme="Authorization-Bearer"
* )
*
*/
（4）Mime类型
| Alias |
MIME Type |
| json |
application/json |
| x-www-form-urlencoded |
application/x-www-form-urlencoded |
| xml |
text/xml |
| plain |
text/plain |
| html |
text/html |
| mpfd |
multipart/form-data |
| json-api |
application/vnd.api+json |
| json-stream |
application/x-json-stream |
| octet-stream |
application/octet-stream |
| png |
image/png |
| jpeg |
image/jpeg |
| gif |
image/gif |
（5）参数类型
● query
● path
● header
● body
● formData
（6）数据类型
● string
● integer
● number
● boolean
● array
● file
（7）swagger-php-官网地址+中文手册
https://github.com/zircote/swagger-php
（三）安装部署步骤
1） 安装swagger-php
composer require zircote/swagger-php:*
2） 根据上方swagger-php模板编写注解
3） 生成swagger-php文档
php ./vendor/zircote/swagger-php/bin/openapi ./app/Http/Controllers -o ./docs/api/swagger.json
安装成功示例
（注意：部分内容转载自，
Swagger php注解常用语法梳理https://www.sdk.cn/details/9pPQD6wqK09L8ozvNy）
网友评论