ThinkPHP与Gin框架之集成SwaggerApi接口文档生成工具-51CTO.COM

大家好，我是码农先森。

想必大家对接口文档都不陌生了，程序员有件很苦恼的事情就是「最讨厌别人的项目不写接口文档，但是又最讨厌自己来写文档」说的是不是你哈哈。虽然很讨厌，但是你也没有办法啊，毕竟人还得吃饭，又不能提桶跑路。其实写接口文档并不全是坏处，好处也是很多的，比如可以减少前后端的扯皮成本、清晰的接口文档可以让对方闭嘴、避免大家乱甩锅等等。

在之前我也不喜欢写接口文档，也不喜欢写注释，然后过一段时间来看自己的代码，结果一脸懵逼自己都看不懂了，我相信大家也这种经历吧，所以嘛有时间还是得写写，避免出现自己挖坑自己跳的尴尬局面。那么这次我主要分享的内容是 SwaggerApi 接口文档，不过有人会质疑了这个东西不是大家都会用了吗？但是我想说的是，你会用但是不代表所有人都会哦，所以呢这篇文章主要是分享给那些还未曾使用过这个工具的人，希望对这些人能有所帮助。

话不多说，开整！我们先来看一下整体的项目目录结构，内容主要分为 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
│   └── .env

ThinkPHP

使用 composer 创建基于 ThinkPHP 框架的 php_swagger 项目。

## 当前目录
[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 相关 Composer 扩展包
[manongsen@root php_swagger]$ composer require zircote/swagger-php
[manongsen@root php_swagger]$ composer require doctrine/annotations

执行 php think make:command Swagger 命令，创建一个用于生成 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('执行成功, 接口文档请访问 http://127.0.0.1:8000/swagger-ui/dist/index.html');

        // 指令输出
        $output->writeln('app\command\swagger');
    }
}

在 php_swagger 项目中执行 php think make:Controller User 命令，创建一个 User 控制器。

<?php

namespace app\controller;

use OpenApi\Annotations as OA;
use app\BaseController;

/**
 * @OA\Info(title="ThinkPHP框架之用户中心系统 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="返回数据",
     *        @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::自行实现具体的业务逻辑
    }

    /**
     * @OA\Get(
     *    description="用户列表",
     *    path="/api/v1/user/list",
     *    @OA\Parameter(in="query", required=false, name="page_size", @OA\Schema(type="integer"), description="页码"),
     *    @OA\Parameter(in="query", required=false, name="page_limit", @OA\Schema(type="integer"), description="条数"),
     *    @OA\Response(
     *        response=200,
     *        description="返回数据",
     *        @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::自行实现具体的业务逻辑
    }

    /**
     * @OA\Post(
     *     description="创建用户",
     *     path="/api/v1/user/create",
     *     @OA\RequestBody(required=true,description="请求数据",content={
     *       @OA\MediaType(mediaType="application/json",
     *           @OA\Schema(
     *               @OA\Property(
     *                   property="username",
     *                   type="string",
     *                   description="用户名"
     *               ),
     *               @OA\Property(
     *                   property="phone",
     *                   type="string",
     *                   description="手机号",
     *               ),
     *               @OA\Property(
     *                   property="email",
     *                   type="string",
     *                   description="邮箱",
     *               )
     *           )
     *       )
     *      }),
     *    @OA\Response(
     *        response=200,
     *        description="返回数据",
     *        @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::自行实现具体的业务逻辑
    }


    /**
     * @OA\Post(
     *     description="更新用户",
     *     path="/api/v1/user/update",
     *     @OA\RequestBody(required=true, description="请求数据", 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="手机号",
     *               ),
     *               @OA\Property(
     *                   property="email",
     *                   type="string",
     *                   description="邮箱",
     *               )
     *           )
     *       )
     *      }),
     *    @OA\Response(
     *        response=200,
     *        description="返回数据",
     *        @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::自行实现具体的业务逻辑
    }
}

先执行 php think swagger 生成 Swagger 文档，然后再执行 php think run 运行项目，最后在浏览器上访问地址 http://127.0.0.1:8000/swagger-ui/dist/index.html 即可看到实际效果。

图片

Gin

通过 go mod 初始化 go_swagger 项目。

## 当前目录
[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 相关依赖库
[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 项目中创建 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} "返回数据"
// @failure 401 string Unauthorized "Unauthorized"
// @failure 404 string NotFound "Not Found"
// @Router /user/info [get]
func UserInfo(c *gin.Context) {
 // TODO::自行实现具体的业务逻辑
}

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  "页码"
// @Param page_limit path int true  "条数"
// @success 200 {object} UserListRespose{data=[]UserStruct} "返回数据"
// @failure 401 string Unauthorized "Unauthorized"
// @failure 404 string NotFound "Not Found"
// @Router /user/list [get]
func UserList(c *gin.Context) {
 // TODO::自行实现具体的业务逻辑
}

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
// 创建用户
// @Summary 创建用户
// @Schemes
// @Description 创建用户
// @Tags user
// @Accept json
// @Produce json
// @Param req body CreateUserRequest true "创建用户"
// @success 200 {object} CreateUserRespose{} "返回数据"
// @failure 401 string Unauthorized "Unauthorized"
// @failure 404 string NotFound "Not Found"
// @Router /user/create [post]
func CreateUser(c *gin.Context) {
 // TODO::自行实现具体的业务逻辑
}

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{} "返回数据"
// @failure 401 string Unauthorized "Unauthorized"
// @failure 404 string NotFound "Not Found"
// @Router /user/update [post]
func UpdateUser(c *gin.Context) {
 // TODO::自行实现具体的业务逻辑
}

先执行 swag init 命令生成 Swagger 文档，然后再执行 go run main.go 运行项目，最后在浏览器上访问 http://127.0.0.1:8080/swagger/index.html 即可看到实际效果。

图片

接口文档是每个项目都不可或缺的部分，同时也是前后端联调接口的桥梁，它让团队的协作效率得到了显著的提升。SwaggerApi 接口文档只需要在相应代码的位置写上对应的注释，便可以通过工具生成文档，这种方式极大的简化了写接口文档的工作量。通过这次内容的分享相信大家对这个工具都有些许的了解了吧，不过最好是能自己再实践一遍，学习的效果会更好。如果有想要获取完整的代码的朋友，可以在公众号内回复「5148」即可获取到，希望对大家能有所帮助，此外为了方便大家学习再附上相关的官方文档。

https://zircote.github.io/swagger-php/
https://github.com/swaggo/swag/blob/master/README.md