APIドキュメントの神器Swaggerの紹介とPHPプロジェクトでの使用

Swaggerは私が今使った最も優秀なApi Docプロトコルの一つではありません.他のApi Docプロトコル(apidocjsなど)との最大の違いは、SwaggerがApiのRoute/Request ParamおよびResponseだけでなく、Definitions Object/Security Definitions ObjectおよびReference Objectも定義できることです.
電子商取引プロジェクトを例にとると、システムには商品(Product)と注文(Order)の2つのModelがあり、Orderにはproduct_idフィールドがあり、対応する商品を関連付けるためのインタフェースが2つあります.1つは商品詳細/product/{product}を取得することであり、もう1つは注文詳細/order/{order}を取得することであり、Api要求数を減らすために、注文詳細を取得する際に対応する商品データを同時に返すことを望んでいます.
apidocjsで書くと次のような注釈になります

/**
 * @api {get} /product/:product Request Product information
 * @apiName GetProduct
 * @apiParam {Number} product Products unique ID.
 * @apiSuccess {String} name Name of the Product.
 * @apiSuccess {Number} price  Price of the Product.
 * @apiSuccess ... Others fields
 */
 
 /**
 * @api {get} /order/:order Request Order information
 * @apiName GetOrder
 * @apiParam {Number} order Orders unique ID.
 * @apiHeader {String} Authorization Access Token.
 * @apiSuccess {String} flow_no FlowNo of the Order.
 * @apiSuccess {String} price  Price of the Order.
 * @apiSuccess {Object} product Product of the Order
 * @apiSuccess {String} product.name Name of the Product.
 * @apiSuccess {Number} product.price  Price of the Product.
 * @apiSuccess ... Others fields
 */

Productのフィールドが2つのインタフェースの注釈に1回ずつ書かれているのが見えますが、これは煩雑です.もう1つの深刻な問題は、将来のProductテーブルのフィールドが増減した場合、Productを出力するインタフェースごとにコメントを変更する必要があり、より煩雑で漏れやすいことです.
Modelフィールドを定義できる機能が必要です.これがSwaggerのDefinitions Objectです.ProductとOrderをDefinitions Objectとして定義しておきます.

Product:
  type: object
  properties:
    id:
      type: integer
    name:
      type: string
      price:
          type: integer

Order:
  type: object
    properties:
      id:
          type: integer
      flow_no:
            type: string
        product:
            $ref: '#/definitions/Product'

Orderのproductフィールドを定義する際、$ref、すなわちReference Objectを使用しました.これは、OrderのproductフィールドがProductの定義を指していることをSwaggerに伝えます.
Route/Request ParamとResponseがSwaggerでどのように書かれているかを見てみましょう.

path:
    /product/{product}:
        get:
            summary: Request Product information
            parameters:
                name: product
                in: path
                required: true
                type: number
            response:
                '200':
                    description: Success
                    schema:
                        $ref: '#/definitions/Product'
    /order/{order}:
        get:
            summary: Request Order information
            parameters:
                name: order
                in: path
                required: true
                type: number
            response:
                '200':
                    description: Success
                    schema:
                        $ref: '#/definitions/Order'

$refにより、増減フィールドを複数修正する必要があるという問題を完璧に解決しました.
私が初めてSwaggerを使用したとき、その強力な定義機能に感心したが、Swaggerドキュメントを書くことを極めて嫌っていた.公式に提供されているSwagger Editorは速度が遅いだけでなく、時々エラーもあった.ドキュメントのフォーマットに問題があることを教えてくれたのに、ページをリフレッシュして再ロードするしかなかった.
最近発見されたプロジェクトswagger-phpは、JSON形式のSwaggerドキュメントを注釈で生成し、\Swagger\scan()関数を使用して、ディレクトリの下にあるすべてのPHPファイルのコメントをスキャンするだけです(コメントのみのphpファイルを作成して、Security Definitions Objectなどのrequest/responseに直接関連のない定義を入れることができます).
JSON形式のドキュメントがあれば、Swagger UIに合わせて非常に美しいApiドキュメントを展示することができます.このDemoを見ることができます.ドキュメントページで直接Apiリクエストを開始することもできます.とても便利です.