Swagger-PHP 自定義生成API 轉

時間 2019-12-10

標籤 swagger php 自定義生成 api 欄目 PHP 简体版

原文原文鏈接

今後接口文檔成爲一笑而過，今後服務端再也不被客戶端追債似得要接口文檔php

主要內容：html

一、項目背景前端

二、Swagger應用java

三、總結nginx

項目背景

做爲一個服務端開發人員，我相信大多數的同窗都會和客戶端開發同窗溝通接口問題。git

可是啊，可是，每當咱們高高興興的開發完成，告訴客戶端和前端同窗能夠調試的時候，一般你們會問一句「文檔呢？」。因而，服務端像是被追債似的加緊時間寫文檔，寫的慢了還要承擔耽誤開發的責任~寫文檔很枯燥有木有，寫文檔很無聊有木有，咱們是開發，不是文員啊，大把時間不用來coding，用來寫文檔，各類表格排版，很頭疼啊頭疼啊頭疼啊（重要的事情說三遍）~ 總之，無論別人喜不喜歡寫文檔，我是不喜歡寫的，並且寫了還要改來改去的╮(╯▽╰)╭。github

終於在陽光明媚的一天，我找到了一個自動生成文檔框架swagger！！！！暗淡的日子終於迎來了曙光。json

PS：抱怨吐槽結束，客戶端勿怪，客戶端的同窗都是很可愛噠。後端

Swagger應用

這章內容說正經的——如何搭建框架。api

此框架目前應用項目——英語口語精華，本項目爲php開發，進行swagger、php整合，可是swagger對於java的支持更爲優秀，有興趣的同窗能夠自行百度（固然google更洋氣）。

swagger簡介

Swagger的使用目的是方便優美的呈現出接口API的各類定義, 生成API文檔, 包括參數, 路徑之類. 有時後端改了API的參數或者其餘設置，同時對於restful風格接口有更加優雅的展現, 前端直接看這個Swagger UI就能夠, 方便項目管理和團隊協做.。

官網是http://swagger.io/。

這東西咋用呢? 說白了就是安裝Swagger套件, 而後API代碼裏寫註釋, 用Swagger後端程序跑API來提取註釋, 生成一個json文件, 再通關Swagger前端來美化,整理JSON數據.

多說顯得嘮叨，上效果圖

swagger搭建過程

swagger主要分爲兩個部分，swagger-ui和swagger-php，ui用於展現，後者用於生成相關api。

首先，在本身項目的合理位置上下載前端ui和生成的php。放在項目裏面是爲了保證訪問地址和我們接口地址都在一塊兒，不會是訪問時產生跨域問題。

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

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

第一步：ui搭建

在ui裏面有個dist文件夾，修改文件夾裏面index.html文件，將url裏的位置寫成本身的項目地址

var url = window.location.search.match(/url=([^&]+)/);
if (url && url.length > 1) {
url = decodeURIComponent(url[1]);
} else {
url = "http://XXXX/doc/swagger.json";
}

hljs.configure({
highlightSizeThreshold: 5000
});

到此位置咱們的ui已經配置完了。

第二步：生成環境搭建

下載swagger-php後，進入此文件夾，使用composer下載swagger-php下載swagger-php所須要的依賴，使用命令行，輸入（前提是安裝了composer）：

composer update

這樣後臺就算完成了搭建，咱們的swagger-php多了vender文件夾

第二步：代碼註解

在咱們的controller的文件中編寫註解，舉個栗子

/**

@SWG\Get(
path="/pets",
description="Returns all pets from the system that the user has access to",
operationId="findPets",
produces=
Unknown macro: {"application/json", "application/xml", "text/xml", "text/html"}
,
@SWG\Parameter(
name="tags",
in="query",
description="tags to filter by",
required=false,
type="array",
@SWG\Items(type="string"),
collectionFormat="csv"
),
@SWG\Parameter(
name="limit",
in="query",
description="maximum number of results to return",
required=false,
type="integer",
format="int32"
),
@SWG\Response(
response=200,
description="pet response",
@SWG\Schema(
type="array",
@SWG\Items(ref="#/definitions/pet")
),
),
@SWG\Response(
response="default",
description="unexpected error",
@SWG\Schema(
ref="#/definitions/errorModel"
)
)
)
*/