Swagger 生成 PHP API 接口文檔

miya 發布于2019-07-01 10:51 / 2712人閱讀

摘要：有同學推薦了，是一個簡單但功能強大的表達工具。這里介紹使用生成文檔的方法。將文檔輸出值的根目錄下，可通過訪問此文檔。執行結果如圖參考資料生成接口文檔如何編寫基于的文檔使用生成文檔不完全指南

Swagger 生成 PHP API 接口文檔

標簽（空格分隔）： php

1、概況

有同學反饋寫幾十個接口文檔需要兩天的工作量, 隨著多部門之間的協作越來越頻繁, 維護成本越來越高, 文檔的可維護性越來越差, 需要一個工具來管理這些接口的文檔, 并能夠充當mock server給調用方使用。

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

2、安裝與使用 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-Swagger

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

2.3 編寫API注解

# 創建文件 demo/customer.php 2.4 生成swagger API 文件

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

API 內容如下:

# 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"

3、展示

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

composer install

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

version: "2"

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

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

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

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

執行 Explore 結果如圖:

4、參考資料

Swagger 生成 PHP restful API 接口文檔

如何編寫基于 Swagger-PHP 的 API 文檔

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

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

Easy Mock

Laravel（PHP）使用Swagger生成API文檔不完全指南

云服務器 GPU云服務器生成API文檔接口文檔生成工具 api接口文檔 api短信接口文檔

文章版權歸作者所有，未經允許請勿轉載,若此文章存在違規行為，您可以聯系管理員刪除。

轉載請注明本文地址：http://specialneedsforspecialkids.com/yun/29560.html

Swagger 生成 PHP restful API 接口文檔

摘要：需求和背景需求為客戶端同事寫接口文檔的各位后端同學已經在各種場合回憶了使用自動化文檔工具前手寫文檔的血淚史我的故事卻又不同因為首先來說我在公司是組負責人屬于上述血淚史中催死人不償命的客戶端陣營但血淚史卻是相通的沒有自動化文檔的日子對接口就是需求和背景需求: 為客戶端同事寫接口文檔的各位后端同學,已經在各種場合回憶了使用自動化文檔工具前手寫文檔的血淚史.我的故事卻又不同,因為首先來說...

xiaotianyi 2019-06-28 18:43 評論0 收藏0
Swagger PHP使用指南

摘要：，已經好了，試著訪問根目錄下，比如試試，出現界面就成功了沒從先就用命令看下的路由最上面條就是剛剛添加的路由。先說什么是Swagger, Swagger的使用目的是方便優美的呈現出接口API的各種定義, 生成API文檔, 包括參數, 路徑之類. 有時后端改了API的參數或者其他設置, 前端直接看這個Swagger UI就可以, 方便項目管理和團隊協作. 官網: http://swagg...

cnio 2019-07-01 10:26 評論0 收藏0
Lumen微服務生成Swagger文檔

摘要：本文將會告訴你如何借助中插件，在開發微服務項目時項目和其它項目方法類似快速的在代碼中使用注釋來創建文檔。本文將會持續修正和更新，最新內容請參考我的上的程序猿成長計劃項目，歡迎，更多精彩內容請。框架配置我們使用當前最新的來演示。 showImg(https://segmentfault.com/img/remote/1460000017715535?w=1072&h=711); 作為一名...

alighters 2019-07-01 11:08 評論0 收藏0
Java | Spring Boot Swagger2 集成REST ful API 生成接口文檔

摘要：集成生成接口文檔原文簡介由于的特性，用來開發變得非常容易，并且結合來自動生成文檔變得方便快捷。使用生成，我們可以得到交互式文檔。聽過與的結合，生成更加完備的文檔。接下來將基于與搭建完整的文檔系統。 Spring Boot Swagger2 集成REST ful API 生成接口文檔原文簡介由于Spring Boot 的特性，用來開發 REST ful 變得非常容易，并且結合 Sw...

joyvw 2019-08-16 10:56 評論0 收藏0
Spring Boot中使用Swagger2構建API文檔

摘要：使用生成，我們可以得到交互式文檔，自動生成代碼的以及的發現特性等。方法指定掃描的包會生成文檔默認是顯示所有接口可以用注解標識該接口不顯示。程序員都很希望別人能寫技術文檔，自己卻很不愿意寫文檔。因為接口數量繁多,并且充滿業務細節,寫文檔需要花大量的時間去處理格式排版,代碼修改后還需要同步修改文檔,經常因為項目時間緊等原因導致文檔滯后于代碼，接口調用方的抱怨聲不絕于耳。而程序員是最擅長偷...

taohonghui 2019-08-15 11:09 評論0 收藏0