swagger系列二：swagger 语法

2019年10月1日 299次阅读 来源: Rango

在swagger-php的Example下有示例写法。拿过来分析记录。

swagger官方注解：https://bfanger.nl/swagger-explained/#schemaObject go

1. 文档标题部分

/**
 * @SWG\Swagger(
 *     schemes={"http"},
 *     host="api.com",
 *     basePath="/v1",
 *     @SWG\Info(
 *         version="1.0.0",
 *         title="API接口文档",
 *         description="测试swagger文档项目",
 *         @SWG\Contact(
 *             name="wxp",
 *             email="panxxxx@163.com"
 *         )
 *     ),
 *      @SWG\ExternalDocumentation(
 *         description="wxp",
 *         url="./"
 *     )
 * )
 */

效果图：

《swagger系列二：swagger 语法》

  • schemes: 接口所支持的协议 (可以填多种协议)
  • host：主机名或ip。
  • basePath：提供API的基本路径，它是相对于host。必须以一个前导斜杠（/）开始. Base URL 是 host + basePath 拼接出来的。

  • Info : 文档描述。

    • version ：版本号。
    • title :标题。
    • description : 描述信息。

  • ExternalDocumentation”:外部文档链接。

    • description:描述
    • url :跳转链接

  • Contact ：联系开发者，发送邮件。

    • name : 开发者姓名
    • email :邮件地址。

2. tag标签部分，用于文档分类

/**
 * @SWG\Tag(
 *   name="pet",
 *   description="你的宠物信息",
 *   @SWG\ExternalDocumentation(
 *     description="查看更多",
 *     url=""
 *   )
 * )
 * @SWG\Tag(
 *   name="store",
 *   description="查看宠物店订单"
 * )
 * @SWG\Tag(
 *   name="user",
 *   description="用户操作记录",
 *   @SWG\ExternalDocumentation(
 *     description="关于宠物店",
 *     url="http://swagger.io"
 *   )
 * )
 */

《swagger系列二：swagger 语法》

  • name : 名称(功能模块)
  • description : 描述

3. 接口注释写法

    /**
     * @SWG\Get(
     *     path="/pet/{petId}",
     *     summary="通过ID查询宠物",
     *     description="返回宠物信息",
     *     operationId="getPetById",
     *     tags={"pet"},
     *     consumes={"application/json", "application/xml"},
     *     produces={"application/xml", "application/json"},
     *     @SWG\Parameter(
     *         description="ID of pet to return",
     *         in="path",
     *         name="petId",
     *         required=true,
     *         type="integer",
     *         format="int64"
     *     ),
     *     @SWG\Response(
     *         response=200,
     *         description="successful operation",
     *         @SWG\Schema(ref="#/definitions/Pet")
     *     ),
     *     @SWG\Response(
     *         response="400",
     *         description="Invalid ID supplied"
     *     ),
     *     @SWG\Response(
     *         response="404",
     *         description="Pet not found"
     *     ),
     *     security={
     *       {"api_key": {}}
     *     }
     * )
     */
  • Get：请求的 HTTP 方法，支持GET/POST/PUT/DELETE 等 HTTP 标准请求方法
  • path：请求的路径
  • summary：接口简介，不能超过120个字符
  • tags：接口标签，可以是多个
  • description：接口描述，支持 Markdown 语法
  • operationId：操作的 ID，全局唯一的接口标识
  • consumes：接口接收的MIME类型，如 application/json
  • produces：接口返回的MIME类型,如 application/json

  • parameters：参数列表

    • description：参数描述
    • in：参数从何处来. 必填. 取值仅限: “query”, “header”, “path”, “formData”, “body”
    • name：参数名.
    • required：参数是否必须. 通过路径传参(in 取值 “path”)时必须为 true.
    • type=参数类型. 取值仅限: “string”, “number”, “integer”, “boolean”, “array”, “file”
    • format：参数格式，如”int64″

  • response: 描叙了来自API操作的单个响应

    • response:返回码
    • description=描述
    • @SWGSchema(ref=”#/definitions/Pet”)： 引用definitions/Pet定义的对象

4. 定义对象

5.type 为array的写法

<?php
/**
 * @SWG\Schema(
 *     property="name",
 *     type="array",
 *     @SWG\Items(
 *          required={"username"}, 
 *          @SWG\Property(
 *              property="firstName",
 *              type="string",
 *              description="firstName"
 *          ),
 *          @SWG\Property(
 *              property="ID",
 *              type="integer",
 *              description="user_id"
 *          ),
 *          @SWG\Property(
 *              property="username",
 *              type="string",
 *              description="username"
 *          )
 *     )
 * )
 */
    原文作者：Rango
    原文地址: https://segmentfault.com/a/1190000014077771
    本文转自网络文章，转载此文章仅为分享知识，如有侵权，请联系博主进行删除。
点赞