swagger系列二:swagger 语法

swagger-phpExample下有示例写法。拿过来分析记录。

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="[email protected]"
 *         )
 *     ),
 *      @SWG\ExternalDocumentation(
 *         description="wxp",
 *         url="./"
 *     )
 * )
 */

效果图:

  • 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"
 *   )
 * )
 */

  • 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的写法

你可能感兴趣的:(laravel,swagger,php)