swagger入门

原创已于 2024-05-22 14:12:51 修改 · 488 阅读

1 ·

CC 4.0 BY-SA版权

文章标签：

#php

于 2021-10-21 14:33:40 首次发布

php基础专栏收录该内容

38 篇文章

订阅专栏

这篇博客介绍了如何利用Swagger PHP库生成API文档。通过在控制器和模型中添加注释，可以详细定义接口的路径、方法、参数、响应等信息。Swagger PHP扫描这些注释并生成JSON格式的Swagger文件，方便开发者查看和理解API接口。同时，文章还提到了Swagger的安全配置、模型定义以及如何简化重复内容的定义。最后，解释了生成Swagger JSON文件的原理和流程。

swagger.php

用于生成swagger文件

<?php
namespace app\index\controller;
/**
 * @SWG\Swagger (
 *          schemes={"https","http"},
 *          host="www.tp.cn",
 *          basePath="/",
 *      @SWG\SecurityScheme(securityDefinition="apikey",type="apiKey",name="token",in="header"),
 *      @SWG\Info (
 *          title="API文档",
 *          version="版本0.1",
 *          description="本文档仅限于测试",
 *          termsOfService="服务网址",
 *          @SWG\Contact(
 *              name="张先生",
 *              url="www.kevlin.com",
 *              email="kevlinzhang.china@gmail.com"
 *
 *          ),
 *          @Swg\License(
 *              name="服务名称-异享律师",
 *              url="http://www.yixianglife.com"
 *          )
 *      ),
 *     @SWG\ExternalDocumentation(
 *          description = "Find out more about my website",
 *          url = "http://www.google.com"
 * )
 *
 *
 * )
 */
class Swagger
{
    public function index()
    {
//        echo __DIR__;
//        $swagger =  \Swagger\scan("/www/wwwroot/default/thinkphp/application/index");
        $swagger =  \Swagger\scan("/www/wwwroot/default/thinkphp/application/index");
        $swagger->saveAs('./swagger.json');
        echo "swagger.json保存成功".rand(1,100);
    }
}

Controller\Test.php

测试demo

<?php
namespace app\index\controller;

class Test
{
    /**
     * @SWG\Post (
     *     path = "/index/test/index",
     *     tags = {"后台管理"},
     *     summary =  "更新用户信息",
     *     security={{"apikey"={}}},
     *     consumes={"application/json","application/xml"},
     *     produces={"application/json","application/xml"},
     *     description="用户的更新逻辑，记得一定要带`token`",
     *     @SWG\Parameter (name="id",type="integer",in="formData",description="商品的id",required=true),
     *     @SWG\Parameter (name="picture",type="file",in="formData",description="商品图片",required=false),
     *     @SWG\Parameter (
     *          in="body",
     *          required=true,
     *          name="bodyName",
     *          description="body description",
     *          @SWG\Schema(
     *                  @SWG\Property (
     *                       property="username",
     *                       type="string",
     *                       example="kevlin"
     *                    ),
     *                  @SWG\Property (
     *                       property="password",
     *                       type="string",
     *                       readOnly=true
     *                    )
     *          )
     *      ),
     *     @SWG\Response(response=200,description="请求成功",
     *          @SWG\Schema(
     *                  @SWG\Property (
     *                      property="code",
     *                      type="number",
     *                      example=10001
     *                  ),
     *                  @SWG\Property (
     *                      property="msg",
     *                      type="string",
     *                      example="返回成功"
     * ),
     *                  @SWG\Property (
     *                      property="data",
     *                      type="object",
     *                      example={"username"="root","password"="111111"}
     *                  )
     *
     *          )
     *      ),
     *     @SWG\Response(response=201,description="请求失败")
     * )
     */
    public function index()
    {

    }

    /**
     * @SWG\Get  (
     *     path = "/index/test/add",
     *     tags = {"接口标签，可以是多个;设置多个相同的tags值,swagger会自动进行逻辑分组"},
     *     summary =  "接口简介",
     *     description =  "接口描述，支持`markdown`语法",
     *     operationId = "操作的id,需要唯一",
     *     security={{"apikey"={}}},
     *     consumes={"application/json","application/xml"},
     *     produces={"application/json"},
     *     @SWG\Parameter (name="id",type="integer",in="formData",description="商品的id",required=true),
     *     @SWG\Response(response=200,description="请求成功",@SWG\Schema(ref="#definitions/TestModel")),
     *     @SWG\Response(response=201,description="请求失败")
     * )
     */
    public function add()
    {

    }
}

Model\Test.php

定义模型（抽取重复定义的内容）

<?php
namespace app\index\model;

/**
 * @SWG\Definition (definition="TestModel")
 */
class Test
{
    /**
     * @SWG\Property (example=100001)
     * @var number
     */
    protected $code;
    /**
     * @SWG\Property (example="ok")
     * @var string
     */
    protected $msg;
    /**
     * @SWG\Property (example={"token":"xxxxxxxx"})
     * @var object
     */
    protected $data;
}

需要注意的是参数items和 collectionFormat 只有参数type=“array”才使用

当参数 in选择“body”时必须定义@SWG\Schema()或schema，通过@SWG\Schema()自定义一个 JSON

Definition请求类型

编写 API 文档时经常会遇到一些 API 的内容是重复的，抽取可以重新定义的内容，定义模型，使用definition来简化我们的文档。

使用`@SWG\Property()`参数来设置

参数	含义
property	名称
type	类型，可以设置值为number,string,integer,boolean,array,object
example	设置默认值
readOnly	属性声明

参数readOnly如果设置为true，这意味着它只作为响应的一部分发送，不能作为请求的一部分发送，默认false

Schema请求类型

参数	含义
ref	允许此路径的外部定义
example	设置一个自定义对象
discriminator	添加多个自定义的ref的支持

例：

/**
*     @SWG\Schema(example={"username"="username","password"="password"})
*/

 * @OA\RequestBody(
 *     required=true,
 *     description="匹配列",
 *     @OA\MediaType(
 *         mediaType="multipart/form-data",
 *         @OA\Schema(
 *             @OA\Property(property="id", type="string", example="1"),
 *             @OA\Property(property="qqcsv",type="file",format="string",description="文件")
 *         )
 *     )
 *
 * )

参考链接：
入门https://blog.youkuaiyun.com/meihuasheng/article/details/118405254

看云：https://www.kancloud.cn/chengguang/swagger-php

我爱学习网：https://www.5axxw.com/wiki/topic/galhwk

laravel5注释

swagger文档

原理：使用zircote读取注释，（使用命令行php ./vendor/zircote/swagger-php/bin/swagger ./vendor/webpower/rest-api/ -o ./public/）生成swagger.json文件（或者yaml文件）；然后访问自定义的swagger.php文件(作用：swagger.json生成index.html到swagger-ui的目录中)；访问的接口文档就是swagger-ui的界面