swagger系列二：swagger 語法

在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="./"
 *     )
 * )
 */

效果圖：

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

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