fyfyu/hyperf-swagger

This package is not installable via Composer 1.x, please make sure you upgrade to Composer 2+. Read more about our Composer 1.x deprecation policy.

this is hyperf annotation document generate package

dev-master 2020-07-08 02:47 UTC

This package is auto-updated.

Last update: 2021-11-08 05:59:50 UTC


README

根据注解生成 API 文档

# 类的注解  分组
use Fyfyu\Swagger\Annotation\Api;
# 方法的注解 接口描述
use Fyfyu\Swagger\Annotation\ApiOperation;
# 参数组的注解
use Fyfyu\Swagger\Annotation\ApiParams;
# 参数的注解
use Fyfyu\Swagger\Annotation\ApiParam;
# 响应注解
use Fyfyu\Swagger\Annotation\ApiResponses;

参数说明

注解参数名称说明其他
Apiname分组名称
ApiOperationname接口名称
ApiOperationdesc接口描述
ApiParamsname参数组名称
ApiParamsvalue参数组数组,多个ApiParam 或者 ApiParams
ApiParamname参数名
ApiParamdesc参数描述
ApiParamtype参数类型 integer string ....
ApiParamrequired是否必填 true or false
ApiParamchildren子参数 , 一般用于响应结果的多维数组数组 多个 ApiParam
ApiResponsesvalue响应组数组,多个ApiParam 或者 ApiParams

安装

	composer require fyfyu/hyperf-swagger

配置

php bin/hyperf.php vendor:public fyfyu/hyperf-swagger

在 config/autoload/swagger.php 中简单配置

使用栗子

<?php

declare(strict_types=1);

namespace App\Controller;
use Hyperf\HttpServer\Annotation\Controller;
use Hyperf\HttpServer\Annotation\GetMapping;

use Fyfyu\Swagger\Annotation\Api;
use Fyfyu\Swagger\Annotation\ApiOperation;
use Fyfyu\Swagger\Annotation\ApiParams;
use Fyfyu\Swagger\Annotation\ApiParam;
use Fyfyu\Swagger\Annotation\ApiResponses;
/**
 * @Api("用户管理")
 * @Controller
 */
class AuthController extends AbstractController
{
    
     /**
      * @ApiOperation(name="用户登录")
      * @ApiParams({
      *     @ApiParams(
      *         name="请求头",
      *         type="header",{
      *             @ApiParam(name="authorization",type="string",desc="token")
      *    }),
      *    @ApiParams(
      *        name="请求参数",{
      *             @ApiParam(name="username",type="string",desc="用户名"),
      *             @ApiParam(name="password",type="string",desc="密码")
      *    })
      * })
      * @ApiResponses({
      *     @ApiResponses(
      *         name="成功响应",
      *         {
      *             @ApiParam(name="status",type="string",desc="状态码"),
      *             @ApiParam(name="data",type="string",desc="数据合集",children={
      *                 @ApiParam(name="username",type="string",desc="用户名"),
      *                 @ApiParam(name="username",type="string",desc="用户名"),
      *                 @ApiParam(name="username",type="string",desc="用户名"),
      *             })
      *         }
      *     ),
      *     @ApiResponses(
      *         name="失败响应",
      *         {
      *             @ApiParam(name="status",type="string",desc="状态码"),
      *             @ApiParam(name="code",type="string",desc="error"),
      *             @ApiParam(name="message",type="string",desc="错误信息")
      *         }
      *     ),
      * })
      * @GetMapping(path="login")
      */
    public function login($id)
    {

    }
    /**
     * @GetMapping(path="logout")
     * @apiOperation(name="退出",desc="用户退出")
     * @ApiParams(
     *  name="请求头",
     *  type="header",
     *  {
     *  @ApiParam(name="authorization")
     * })
     */
    public function logout(){

    }
    
}

查看接口

 php bin/hyperf.php swagger:gen 

可指定参数 -S server.php 中的服务名称 默认 http -P 路由地址 -E 导出

栗子

 php bin/hyperf.php swagger:gen  -S admin
 php bin/hyperf.php swagger:gen  -P auth/login
 php bin/hyperf.php swagger:gen  -S admin -E 

展示

hyperf 注解文档生成

hyperf 注解文档生成

hyperf 注解文档生成

hyperf 注解文档生成

hyperf 注解文档生成

目前仅支持导出 easydoc.xyz 的 json api文件 可以在 easydoc.xyz 中导入 实现模拟请求等 后期会支持更多和内置接口展示。