## **swagger注释说明**
注释关键词列表
| 名称 | 说明 |
| --- | --- |
| OpenApi | - |
| Server | 接口服务说明 |
| Info | 接口服务详细信息 |
| Schema | - |
| ExternalDocumentation | - |
| Tag | - |
| Contact | - |
| License | - |
| Post | - |
| Get | - |
| Put | - |
| Delete | - |
|Response | - |
|MediaType | - |
|JsonContent | - |
|XmlContent | - |
|Schema | - |
|Xml | - |
|Property | - |
|Parameter | - |
|RequestBody | - |
#### **@OA\OpenApi**
开放接口顶级对象，可包含下列所有对象。
```
/**
* @OA\OpenApi(
* @OA\Info(
* version="1.0.0",
* title="Swagger Petstore",
* @OA\License(name="MIT")
* ),
* @OA\Server(
* description="Api server",
* url="petstore.swagger.io",
* ),
* )
*/
```
> 您不应将所有注释放在一个大的`@OA\OpenApi()`注释块中，而是将它们分散到整个代码库中。swagger-php将扫描您的项目并将所有注释合并到一个`@OA\OpenApi`注释中。
#### **@OA\Server**
设置数据服务的地址，可设置多个。
| 名称 | 说明 | 示例 |
| --- | --- |--- |
| description | 描述 | - |
| url | 地址，若带http/https，接口地址为url；不带，接口地址则为当前域名+url | - |
```
/**
* @OA\Server(
* description="Mock测试接口地址",
* url="https://virtserver.swaggerhub.com/swagger/Petstore/1.0.0"
* )
* @OA\Server(
* description="正式接口",
* url="/v1"
* )
*/
```
#### **@OA\ExternalDocumentation**
外部文档说明
| 名称 | 说明 | 示例 |
| --- | --- |--- |
| description | 描述 | - |
| url | 地址 | - |
```
/**
* @OA\ExternalDocumentation(
* description="Find out more about Swagger",
* url="http://swagger.io"
* )
*/
```
#### **@OA\Info**
接口服务信息
| 名称 | 说明 | 示例 |
| --- | --- |--- |
| description | 描述 | - |
| version | 版本号 | 1.0.0 |
| title | 接口服务标题 | - |
| termsOfService | 服务条款 | http://swagger.io/terms/ |
| @OA\Contact | 联系方式 | - |
| @OA\License | 许可证 |- |
```
/**
* @OA\Info(
* description="This is a sample Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).",
* version="1.0.0",
* title="Swagger Petstore",
* termsOfService="http://swagger.io/terms/",
* @OA\Contact(
* email="apiteam@swagger.io"
* ),
* @OA\License(
* name="Apache 2.0",
* url="http://www.apache.org/licenses/LICENSE-2.0.html"
* )
* )
*/
```
**@OA\Tag**
接口分类标签，包含一组接口
| 名称 | 说明 | 示例 |
| --- | --- |--- |
| name| 名称 | - |
| description | 描述 | - |
| @OA\ExternalDocumentation | 外部文档信息 | - |
```
/**
* @OA\Tag(
* name="pet",
* description="Everything about your Pets",
* @OA\ExternalDocumentation(
* description="Find out more",
* url="http://swagger.io"
* )
* )
* @OA\Tag(
* name="store",
* description="Access to Petstore orders",
* )
* @OA\Tag(
* name="user",
* description="Operations about user",
* @OA\ExternalDocumentation(
* description="Find out more about store",
* url="http://swagger.io"
* )
* )
*/
```
#### **@OA\Post**
Post请求接口，新建一个资源
| 名称 | 说明 | 示例 |
| --- | --- |--- |
| path | url地址 | - |
| tags| 所属分类标签，`@OA\Tag`的name值 | - |
| summary | 简介 | - |
| description | 详细说明，开头使用`>`，且单独占一行，可高亮显示信息。 | - |
| operationId | 执行的方法 | - |
| deprecated | 是否弃用 | - |
| security | 安全验证 | - |
| requestBody | 请求内容 | - |
| @OA\Parameter | 传递的参数 | - |
| @OA\Response | 响应信息 | - |
```
/**
* @OA\Post(
* path="/pet",
* tags={"pet"},
* summary="Add a new pet to the store",
* description=">
具体说明，另起一行。具体说明具体说明具体说明
换行，具体说明具体说明具体说明",
* operationId="addPet",
* @OA\Response(
* response=405,
* description="Invalid input"
* ),
* security={
* {"petstore_auth": {"write:pets", "read:pets"}}
* },
* requestBody={"$ref": "#/components/requestBodies/Pet"}
* )
*/
```
#### **@OA\Put**
Put请求接口，更新一个资源。说明同`@OA\Post`
```
/**
* @OA\Put(
* path="/pet",
* tags={"pet"},
* summary="Update an existing pet",
* operationId="updatePet",
* @OA\Response(
* response=400,
* description="Invalid ID supplied"
* ),
* @OA\Response(
* response=404,
* description="Pet not found"
* ),
* @OA\Response(
* response=405,
* description="Validation exception"
* ),
* security={
* {"petstore_auth": {"write:pets", "read:pets"}}
* },
* requestBody={"$ref": "#/components/requestBodies/Pet"}
* )
*/
```
#### **@OA\Get**
Get请求接口，读取一个资源。
```
/**
* @OA\Get(
* path="/pet/findByStatus",
* tags={"pet"},
* summary="Finds Pets by status",
* description="Multiple status values can be provided with comma separated string",
* operationId="findPetsByStatus",
* deprecated=true,
* @OA\Parameter(
* name="status",
* in="query",
* description="Status values that needed to be considered for filter",
* required=true,
* explode=true,
* @OA\Schema(
* type="array",
* default="available",
* @OA\Items(
* type="string",
* enum = {"available", "pending", "sold"},
* )
* )
* ),
* @OA\Response(
* response=200,
* description="successful operation",
* @OA\JsonContent(
* type="array",
* @OA\Items(ref="#/components/schemas/Pet")
* ),
* @OA\XmlContent(
* type="array",
* @OA\Items(ref="#/components/schemas/Pet")
* )
* ),
* @OA\Response(
* response=400,
* description="Invalid status value"
* ),
* security={
* {"petstore_auth": {"write:pets", "read:pets"}}
* }
* )
*/
```
#### **@OA\Delete**
Delete请求接口，删除一个资源。
~~~
/**
* @OA\Delete(
* path="/pet/{petId}",
* tags={"pet"},
* summary="Deletes a pet",
* operationId="deletePet",
* @OA\Parameter(
* name="api_key",
* in="header",
* required=false,
* @OA\Schema(
* type="string"
* )
* ),
* @OA\Parameter(
* name="petId",
* in="path",
* description="Pet id to delete",
* required=true,
* @OA\Schema(
* type="integer",
* format="int64"
* ),
* ),
* @OA\Response(
* response=400,
* description="Invalid ID supplied",
* ),
* @OA\Response(
* response=404,
* description="Pet not found",
* ),
* security={
* {"petstore_auth": {"write:pets", "read:pets"}}
* },
* )
*/
~~~
#### **@OA\Response**
服务端响应结果，有的接口会设置多个响应结果。
| 名称 | 说明 | 示例 |
| --- | --- |--- |
| response | 响应码 | 200，400 |
| description | 描述 | - |
| @OA\JsonContent | 返回json内容 | @OA\JsonContent(ref="#/components/schemas/Order")，指向模型，Order为类名 |
| @OA\XmlContent| 返回xml内容 | @OA\XmlContent(ref="#/components/schemas/Order"), |
| @OA\MediaType | 设置类型 | - |
#### **@OA\MediaType**
设置资源类型
| 名称 | 说明 | 示例 |
| --- | --- |--- |
| mediaType | 类型 | `application/xml`，`application/json`，`application/octet-stream`，`application/x-www-form-urlencoded`，`multipart/form-data`，`application/json`，`text/xml` |
| @OA\Schema | 数据结构 | - |
```
@OA\MediaType(
mediaType="application/xml",
@OA\Schema(ref="#/components/schemas/Order")
),
@OA\MediaType(
mediaType="application/json",
@OA\Schema(ref="#/components/schemas/User"),
)
```
但由于大多数API请求和响应都是JSON，因此可使用`@OA\JsonContent`简写：
```
@OA\JsonContent(ref="#/components/schemas/Pet"),
@OA\JsonContent(
type="array",
@OA\Items(ref="#/components/schemas/Pet")
),
// Xml类似
@OA\XmlContent(ref="#/components/schemas/Pet"),
@OA\XmlContent(
type="array",
@OA\Items(ref="#/components/schemas/Pet")
),
```
#### **@OA\Schema**
数据结构
| 名称 | 说明 | 示例 |
| --- | --- |--- |
| title | 数据模型名称，若设置此属性，代表是一个数据模型，编写模型必须声明Class类。 | - |
| type | 数据类型，不设置，默认为对象 | `integer`，`string`，`array`，`object` |
| format | 格式 | `int64`,`binary` |
| minimum | 最小值 | 1 |
| maximum | 最大值 | 10 |
| description | 描述 | - |
| required | 必填字段 | {"code", "message"} |
| schema | 重新定义数据模型名称 | newPet ,使用@OA\JsonContent(ref="#/components/schemas/NewPet") |
| @OA\Property | 添加属性 | - |
| @OA\Xml | 设置xml格式信息 | - |
`type`和`format`对应值
| [`type`](https://swagger.io/specification/#dataTypes) | [`format`](https://swagger.io/specification/#dataTypeFormat) | 说明 |
| --- | --- | --- |
| `integer` | `int32` | signed 32 bits |
| `integer` | `int64` | signed 64 bits (a.k.a long) |
| `number` | `float` | |
| `number` | `double` | |
| `string` | | |
| `string` | `byte` | base64 encoded characters |
| `string` | `binary` | any sequence of octets |
| `boolean` | | |
| `string` | `date` | As defined by`full-date`\-[RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14) |
| `string` | `date-time` | As defined by`date-time`\-[RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14) |
| `string` | `password` | A hint to UIs to obscure input. |
```
@OA\Schema(
type="integer",
format="int64",
maximum=10,
minimum=1
)
```
@OA\Schema可直接使用`ref`直接指向一个模型。
```
@OA\Schema(ref="#/components/schemas/User")
```
当属性`type`为数组时，使用`@OA\Items`描述成员类型：
```
@OA\Schema(
type="array",
@OA\Items(
type="string",
)
)
```
> @OA\JsonContent，@OA\XmlContent设置同@OA\Schema。
**创建一个数据模型**
```php
<?php
/**
* Class Order
*
* @package Petstore30
* @author Donii Sergii <doniysa@gmail.com>
*
* 创建数据模型
* @OA\Schema(
* title="Order model",
* description="Order model",
* )
*/
class Order
{
/**
* 添加属性（字段）
* @OA\Property(
* format="int64",
* title="ID",
* default=1,
* description="ID",
* )
*
* @var integer
*/
private $id;
/**
* @OA\Property(
* default=1,
* format="int64",
* description="Pet ID",
* title="Pet ID",
* )
*
* @var integer
*/
private $petId;
/**
* @OA\Property(
* default=12,
* format="in32",
* description="Quantity",
* title="Quantity",
* )
*
* @var integer
*/
private $quantity;
/**
* @OA\Property(
* default="2017-02-02 18:31:45",
* format="datetime",
* description="Shipping date",
* title="Shipping date",
* title="Pet ID",
* type="string"
* )
*
* @var \DateTime
*/
private $shipDate;
/**
* @OA\Property(
* default="placed",
* title="Order status",
* description="Order status",
* enum={"placed", "approved", "delivered"},
* title="Pet ID",
* )
*
* @var string
*/
private $status;
/**
* @OA\Property(
* default="false",
* format="int64",
* description="Complete status",
* title="Complete status",
* )
*
* @var boolean
*/
private $complete;
}
```
使用`@OA\Xml`
```
@OA\Schema(
title="Order model",
description="Order model",
@OA\Xml(
name="Tag"
)
)
```
使用`required`
```
@OA\Schema(required={"code", "message"})
```
**`@OA\Schema`和`allOf`结合使用**
```php
<?php
namespace Petstore;
/**
* @OA\Schema(schema="NewPet", required={"name"})
*/
class SimplePet
{
public $id;
/**
* @OA\Property()
* @var string
*/
public $name;
/**
* @var string
* @OA\Property()
*/
public $tag;
}
/**
* @OA\Schema(
* schema="Pet",
* type="object",
* allOf={
* @OA\Schema(ref="#/components/schemas/NewPet"),
* @OA\Schema(
* required={"id"},
* @OA\Property(property="id", format="int64", type="integer")
* )
* }
* )
*/
```
阅读[继承和多态性](https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/)章节中的更多信息。
#### **@OA\Property**
设置数据结构`@OA\Schema`属性
| 名称 | 说明 | 示例 |
| --- | --- |--- |
| title | 属性名称 | - |
| property | 定义属性名 | |
| description | 描述 | - |
| default | 默认值 | - |
| type | 数据类型 | `integer`，`string`，`array` |
| format | 格式 | `int64`,`binary` |
| enum | 枚举内容 | enum = {"available", "pending", "sold"} |
#### **@OA\Parameter**
设置请求参数
| 名称 | 说明 | 示例 |
| --- | --- |--- |
| name| 名称 | - |
| in | 参数所在位置 | `body`：requestBody中，一般用于Post提交，`query`：作为url的参数，`path`：作为url路径的一部分，`header`：请求头中，`cookie`：cookie中 |
| description | 描述 | - |
| required | 是否必填 | - |
| explode| 值是否以数组格式提交。当为`false`，默认使用逗号隔开拼接成字符串 | - |
| @OA\Schema | 数据结构 | - |
```
@OA\Parameter(
name="tags",
in="query",
description="Tags to filter by",
required=true,
explode=true,
@OA\Schema(
type="array",
@OA\Items(
type="string",
)
)
),
```
#### **@OA\RequestBody**
设置请求内容。
| 名称 | 说明 | 示例 |
| --- | --- |--- |
| description | 描述 | - |
| @OA\MediaType | 类型设置 | - |
以下代码，设置请求类型为`application/x-www-form-urlencoded`，并设置2个参数。
`application/x-www-form-urlencoded`把form数据转换成一个字串（name1=value1&name2=value2…）
```
@OA\RequestBody(
description="Input data format",
@OA\MediaType(
mediaType="application/x-www-form-urlencoded",
@OA\Schema(
type="object",
@OA\Property(
property="name",
description="Updated name of the pet",
type="string",
),
@OA\Property(
property="status",
description="Updated status of the pet",
type="string"
)
)
)
)
```
使用`ref`指向数据结构
```
requestBody={"$ref": "#/components/requestBodies/Pet"}
/**
*
* @OA\RequestBody(
* request="Pet",
* description="Pet object that needs to be added to the store",
* required=true,
* @OA\JsonContent(ref="#/components/schemas/Pet"),
* @OA\MediaType(
* mediaType="application/xml",
* @OA\Schema(ref="#/components/schemas/Pet")
* )
* )
*/
```
更多使用请阅读`./项目目录/vendor/zircote/swagger-php/Examples`目录下代码
