Swagger 生成 PHP API 接口文檔

時間 2019-11-07

標籤 swagger 生成 php api 接口文檔欄目 PHP 简体版

原文原文鏈接

Swagger 生成 PHP API 接口文檔

標籤（空格分隔）： phpphp

一、概況

有同窗反饋寫幾十個接口文檔須要兩天的工做量, 隨着多部門之間的協做愈來愈頻繁, 維護成本愈來愈高, 文檔的可維護性愈來愈差, 須要一個工具來管理這些接口的文檔, 並可以充當mock server給調用方使用。html

有同窗推薦了swagger+easymock，Swagger是一個簡單但功能強大的API表達工具。這裏介紹使用swagger-php生成PHP API文檔的方法。nginx

二、安裝與使用

2.1 安裝swagger-php包

git clone https://github.com/zircote/swagger-php.git

composer install

// 全局的
composer global require zircote/swagger-php

// 項目中
composer global require zircote/swagger-php

2.2 laravel項目安裝

使用 L5 Swagger https://github.com/DarkaOnLine/L5-Swaggerlaravel

具體安裝過程請參考此文檔: https://github.com/DarkaOnLin...git

2.3 編寫API註解

# 建立文件 demo/customer.php
<?php

/**
 * @OA\Info(title="My First API", version="0.1")
 */
class Customer
{
    /**
     * @OA\Get(
     *     path="/customer/info",
     *     summary="用戶的我的信息",
     *     description="這不是個api接口,這個返回一個頁面",
     *     @OA\Parameter(name="userId", in="query", @OA\Schema(type="string"), required=true, description="用戶ID"),
     *     @OA\Response(
     *      response="200",
     *      description="An example resource"
     *     )
     * )
     */
    public function info(int $userId, string $userToken)
    {

    }
}

2.4 生成swagger API 文件

./swagger-php/bin/openapi demo -o ./docs

API 內容以下:github

# docs/openapi.yaml
openapi: 3.0.0
info:
  title: 'My First API'
  version: '0.1'
paths:
  /customer/info:
    get:
      summary: 用戶的我的信息
      description: '這不是個api接口,這個返回一個頁面'
      operationId: 'Customer::info'
      parameters:
        -
          name: userId
          in: query
          description: 用戶ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'An example resource'

三、展現

git clone https://github.com/swagger-api/swagger-ui.git

composer install

直接經過Dockerfile構建、啓動項目，或者使用docker-compose進行服務管理。docker

version: '2'

services:
    swagger-ui:
      build: .
      ports:
        - "8080:8080"
      volumes:
        - ./dist/:/usr/share/nginx/html/
      restart: on-failure

訪問 http://localhost:8080/ 便可到 swagger 編輯器預覽界面。api

./swagger-php/bin/openapi demo -o ./swagger-ui/dist/

將 api文檔輸出值swagger ui的根目錄下，可經過 http://localhost:8080/openapi.yaml 訪問此api文檔。restful

執行 Explore 結果如圖:composer

四、參考資料

相關標籤/搜索

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。