ThinkPHP與Gin框架之集成SwaggerApi接口文檔生成工具
作者：碼農(nóng)先森
SwaggerApi 接口文檔只需要在相應(yīng)代碼的位置寫上對(duì)應(yīng)的注釋，便可以通過(guò)工具生成文檔，這種方式極大的簡(jiǎn)化了寫接口文檔的工作量。
大家好，我是碼農(nóng)先森。
想必大家對(duì)接口文檔都不陌生了，程序員有件很苦惱的事情就是「最討厭別人的項(xiàng)目不寫接口文檔，但是又最討厭自己來(lái)寫文檔」說(shuō)的是不是你哈哈。雖然很討厭，但是你也沒(méi)有辦法啊，畢竟人還得吃飯，又不能提桶跑路。其實(shí)寫接口文檔并不全是壞處，好處也是很多的，比如可以減少前后端的扯皮成本、清晰的接口文檔可以讓對(duì)方閉嘴、避免大家亂甩鍋等等。
在之前我也不喜歡寫接口文檔，也不喜歡寫注釋，然后過(guò)一段時(shí)間來(lái)看自己的代碼，結(jié)果一臉懵逼自己都看不懂了，我相信大家也這種經(jīng)歷吧，所以嘛有時(shí)間還是得寫寫，避免出現(xiàn)自己挖坑自己跳的尷尬局面。那么這次我主要分享的內(nèi)容是 SwaggerApi 接口文檔，不過(guò)有人會(huì)質(zhì)疑了這個(gè)東西不是大家都會(huì)用了嗎？但是我想說(shuō)的是，你會(huì)用但是不代表所有人都會(huì)哦，所以呢這篇文章主要是分享給那些還未曾使用過(guò)這個(gè)工具的人，希望對(duì)這些人能有所幫助。
話不多說(shuō)，開(kāi)整！我們先來(lái)看一下整體的項(xiàng)目目錄結(jié)構(gòu)，內(nèi)容主要分為 PHP 和 Go 兩部分。
[manongsen@root php_to_go]$ tree -L 2
.
├── go_swagger
│ ├── app
│ │ ├── controller
│ │ │ └── user.go
│ │ └── route.go
│ ├── go.mod
│ ├── go.sum
│ └── main.go
└── php_swagger
│ ├── app
│ │ ├── command
│ │ │ └── Swagger.php
│ │ ├── controller
│ │ │ └── User.php
│ ├── composer.json
│ ├── composer.lock
│ ├── config
│ ├── public
│ │ |── swagger-ui
│ │ └── swagger.json
│ ├── route
│ │ └── app.php
│ ├── think
│ ├── vendor
│ └── .envThinkPHP
使用 composer 創(chuàng)建基于 ThinkPHP 框架的 php_swagger 項(xiàng)目。
## 當(dāng)前目錄
[manongsen@root ~]$ pwd
/home/manongsen/workspace/php_to_go/php_swagger
## 安裝 ThinkPHP 框架
[manongsen@root php_swagger]$ composer create-project topthink/think php_swagger
[manongsen@root php_swagger]$ cp .example.env .env
## 安裝 Swagger 相關(guān) Composer 擴(kuò)展包
[manongsen@root php_swagger]$ composer require zircote/swagger-php
[manongsen@root php_swagger]$ composer require doctrine/annotations執(zhí)行 php think make:command Swagger 命令，創(chuàng)建一個(gè)用于生成 Swagger 文檔的腳本。
<?php
declare (strict_types = 1);
namespace app\command;
use think\console\Command;
use think\console\Input;
use think\console\input\Argument;
use think\console\input\Option;
use think\console\Output;
use app;
use OpenApi\Generator;
class Swagger extends Command
{
protected function configure()
{
// 指令配置
$this->setName('app\command\swagger')
->setDescription('the app\command\swagger command');
}
protected function execute(Input $input, Output $output)
{
$openapi = \OpenApi\Generator::scan([__DIR__ . '/../../app/controller/']);
file_put_contents(__DIR__ . '/../../public/swagger.json', $openapi->toJson());
$output->writeln('執(zhí)行成功, 接口文檔請(qǐng)?jiān)L問(wèn) http://127.0.0.1:8000/swagger-ui/dist/index.html');
// 指令輸出
$output->writeln('app\command\swagger');
}
}在 php_swagger 項(xiàng)目中執(zhí)行 php think make:Controller User 命令，創(chuàng)建一個(gè) User 控制器。
<?php
namespace app\controller;
use OpenApi\Annotations as OA;
use app\BaseController;
/**
* @OA\Info(title="ThinkPHP框架之用戶中心系統(tǒng) API", version="1.0")
*/
class User extends BaseController
{
/**
* @OA\Get(
* description="用戶詳情",
* path="/api/v1/user/info",
* @OA\Parameter(in="query", required=true, name="user_id", @OA\Schema(type="integer"), description="用戶ID"),
* @OA\Response(
* response=200,
* description="返回?cái)?shù)據(jù)",
* @OA\JsonContent(type="object",
* @OA\Property(property="code", type="int"),
* @OA\Property(property="message", type="string"),
* @OA\Property(property="data", type="object",
* @OA\Property(property="user_id", type="integer"),
* @OA\Property(property="user_name", type="string"),
* @OA\Property(property="mobile", type="string"),
* @OA\Property(property="email", type="string"),
* ),
* ),
* ),
* @OA\Response(response=401, description="Unauthorized"),
* @OA\Response(response=404, description="Not Found"),
* )
*/
public function info()
{
// TODO::自行實(shí)現(xiàn)具體的業(yè)務(wù)邏輯
}
/**
* @OA\Get(
* description="用戶列表",
* path="/api/v1/user/list",
* @OA\Parameter(in="query", required=false, name="page_size", @OA\Schema(type="integer"), description="頁(yè)碼"),
* @OA\Parameter(in="query", required=false, name="page_limit", @OA\Schema(type="integer"), description="條數(shù)"),
* @OA\Response(
* response=200,
* description="返回?cái)?shù)據(jù)",
* @OA\JsonContent(type="object",
* @OA\Property(property="code", type="int"),
* @OA\Property(property="message", type="string"),
* @OA\Property(property="data", type="array",
* @OA\Items(type="object",
* @OA\Property(property="user_id", type="integer"),
* @OA\Property(property="user_name", type="string"),
* @OA\Property(property="mobile", type="string"),
* @OA\Property(property="email", type="string"),
* ),
* ),
* ),
* ),
* @OA\Response(response=401, description="Unauthorized"),
* @OA\Response(response=404, description="Not Found"),
* )
*/
public function list()
{
// TODO::自行實(shí)現(xiàn)具體的業(yè)務(wù)邏輯
}
/**
* @OA\Post(
* description="創(chuàng)建用戶",
* path="/api/v1/user/create",
* @OA\RequestBody(required=true,description="請(qǐng)求數(shù)據(jù)",content={
* @OA\MediaType(mediaType="application/json",
* @OA\Schema(
* @OA\Property(
* property="username",
* type="string",
* description="用戶名"
* ),
* @OA\Property(
* property="phone",
* type="string",
* description="手機(jī)號(hào)",
* ),
* @OA\Property(
* property="email",
* type="string",
* description="郵箱",
* )
* )
* )
* }),
* @OA\Response(
* response=200,
* description="返回?cái)?shù)據(jù)",
* @OA\JsonContent(type="object",
* @OA\Property(property="code", type="int"),
* @OA\Property(property="message", type="string"),
* ),
* ),
* @OA\Response(response=401, description="Unauthorized"),
* @OA\Response(response=404, description="Not Found"),
* )
* )
*/
public function create()
{
// TODO::自行實(shí)現(xiàn)具體的業(yè)務(wù)邏輯
}
/**
* @OA\Post(
* description="更新用戶",
* path="/api/v1/user/update",
* @OA\RequestBody(required=true, description="請(qǐng)求數(shù)據(jù)", content={
* @OA\MediaType(mediaType="application/json",
* @OA\Schema(
* @OA\Property(
* property="user_id",
* type="integer",
* description="用戶ID",
* ),
* @OA\Property(
* property="username",
* type="string",
* description="用戶名"
* ),
* @OA\Property(
* property="phone",
* type="string",
* description="手機(jī)號(hào)",
* ),
* @OA\Property(
* property="email",
* type="string",
* description="郵箱",
* )
* )
* )
* }),
* @OA\Response(
* response=200,
* description="返回?cái)?shù)據(jù)",
* @OA\JsonContent(type="object",
* @OA\Property(property="code", type="int"),
* @OA\Property(property="message", type="string"),
* ),
* ),
* @OA\Response(response=401, description="Unauthorized"),
* @OA\Response(response=404, description="Not Found"),
* )
* )
*/
public function update()
{
// TODO::自行實(shí)現(xiàn)具體的業(yè)務(wù)邏輯
}
}先執(zhí)行 php think swagger 生成 Swagger 文檔，然后再執(zhí)行 php think run 運(yùn)行項(xiàng)目，最后在瀏覽器上訪問(wèn)地址 http://127.0.0.1:8000/swagger-ui/dist/index.html 即可看到實(shí)際效果。
圖片
Gin
通過(guò) go mod 初始化 go_swagger 項(xiàng)目。
## 當(dāng)前目錄
[manongsen@root ~]$ pwd
/home/manongsen/workspace/php_to_go/go_swagger
[manongsen@root go_swagger]$ go mod init go_swagger
## 安裝 Gin 框架
[manongsen@root go_swagger]$ go get github.com/gin-gonic/gin
## 安裝 Swagger 相關(guān)依賴庫(kù)
[manongsen@root go_swagger]$ go get github.com/swaggo/files
[manongsen@root go_swagger]$ go get github.com/swaggo/gin-swagger
## 安裝 Swagger 文檔生成工具
[manongsen@root go_swagger]$ go install github.com/swaggo/swag/cmd/swag@latest在 go_swagger 項(xiàng)目中創(chuàng)建 user 控制器。
package controller
import (
"github.com/gin-gonic/gin"
)
type UserStruct struct {
UserId string `json:"user_id"`
UserName string `json:"user_name"`
Mobile string `json:"mobile"`
Email string `json:"email"`
}
type UserInfoRespose struct {
Code int `json:"code" `
Message string `json:"message"`
Data UserStruct `json:"data"`
}
// @BasePath /api/v1
// 用戶信息
// @Summary 用戶信息
// @Schemes
// @Description 用戶信息
// @Tags user
// @Produce json
// @Param id path int true "用戶ID"
// @success 200 {object} UserInfoRespose{data=UserStruct} "返回?cái)?shù)據(jù)"
// @failure 401 string Unauthorized "Unauthorized"
// @failure 404 string NotFound "Not Found"
// @Router /user/info [get]
func UserInfo(c *gin.Context) {
// TODO::自行實(shí)現(xiàn)具體的業(yè)務(wù)邏輯
}
type UserListRespose struct {
Code int `json:"code" `
Message string `json:"message"`
Data []*UserStruct `json:"data"`
}
// @BasePath /api/v1
// 用戶列表
// @Summary 用戶列表
// @Schemes
// @Description 用戶列表
// @Tags user
// @Produce json
// @Param page_size path int true "頁(yè)碼"
// @Param page_limit path int true "條數(shù)"
// @success 200 {object} UserListRespose{data=[]UserStruct} "返回?cái)?shù)據(jù)"
// @failure 401 string Unauthorized "Unauthorized"
// @failure 404 string NotFound "Not Found"
// @Router /user/list [get]
func UserList(c *gin.Context) {
// TODO::自行實(shí)現(xiàn)具體的業(yè)務(wù)邏輯
}
type CreateUserRequest struct {
UserName string `json:"user_name"`
Mobile string `json:"mobile"`
Email string `json:"email"`
}
type CreateUserRespose struct {
Code int `json:"code" `
Message string `json:"message"`
}
// @BasePath /api/v1
// 創(chuàng)建用戶
// @Summary 創(chuàng)建用戶
// @Schemes
// @Description 創(chuàng)建用戶
// @Tags user
// @Accept json
// @Produce json
// @Param req body CreateUserRequest true "創(chuàng)建用戶"
// @success 200 {object} CreateUserRespose{} "返回?cái)?shù)據(jù)"
// @failure 401 string Unauthorized "Unauthorized"
// @failure 404 string NotFound "Not Found"
// @Router /user/create [post]
func CreateUser(c *gin.Context) {
// TODO::自行實(shí)現(xiàn)具體的業(yè)務(wù)邏輯
}
type UpdateUserRequest struct {
UserId string `json:"user_id"`
UserName string `json:"user_name"`
Mobile string `json:"mobile"`
Email string `json:"email"`
}
type UpdateUserRespose struct {
Code int `json:"code" `
Message string `json:"message"`
}
// @BasePath /api/v1
// 更新用戶
// @Summary 更新用戶
// @Schemes
// @Description
// @Tags user
// @Accept json
// @Produce json
// @Param req body UpdateUserRequest true "更新用戶"
// @success 200 {object} UpdateUserRespose{} "返回?cái)?shù)據(jù)"
// @failure 401 string Unauthorized "Unauthorized"
// @failure 404 string NotFound "Not Found"
// @Router /user/update [post]
func UpdateUser(c *gin.Context) {
// TODO::自行實(shí)現(xiàn)具體的業(yè)務(wù)邏輯
}先執(zhí)行 swag init 命令生成 Swagger 文檔，然后再執(zhí)行 go run main.go 運(yùn)行項(xiàng)目，最后在瀏覽器上訪問(wèn) http://127.0.0.1:8080/swagger/index.html 即可看到實(shí)際效果。
圖片
接口文檔是每個(gè)項(xiàng)目都不可或缺的部分，同時(shí)也是前后端聯(lián)調(diào)接口的橋梁，它讓團(tuán)隊(duì)的協(xié)作效率得到了顯著的提升。SwaggerApi 接口文檔只需要在相應(yīng)代碼的位置寫上對(duì)應(yīng)的注釋，便可以通過(guò)工具生成文檔，這種方式極大的簡(jiǎn)化了寫接口文檔的工作量。通過(guò)這次內(nèi)容的分享相信大家對(duì)這個(gè)工具都有些許的了解了吧，不過(guò)最好是能自己再實(shí)踐一遍，學(xué)習(xí)的效果會(huì)更好。如果有想要獲取完整的代碼的朋友，可以在公眾號(hào)內(nèi)回復(fù)「5148」即可獲取到，希望對(duì)大家能有所幫助，此外為了方便大家學(xué)習(xí)再附上相關(guān)的官方文檔。
- https://zircote.github.io/swagger-php/
- https://github.com/swaggo/swag/blob/master/README.md
責(zé)任編輯：武曉燕
來(lái)源：
碼農(nóng)先森
