脚本之家 服务器常用软件
快捷导航
您的位置：首页 → 网络编程 → PHP编程 → php技巧 → PHP Swagger

PHP使用Swagger生成好看的API文档

 更新时间：2023年02月15日 15:46:27   作者：HOOLOO  
api文档不能根据代码的变化发生实时动态的改变，这样后端修改了接口，前端不能及时获取最新的接口，导致调用出错，需要手动维护api文档，加大了开发的工作量和困难，而swagger的出现就是为了解决这一系列的问题

PHP使用Swagger生成好看的API文档不是不可能，而是非常简单。

首先本人使用Laravel框架，所以在Laravel上安装swagger-php。

一、安装swagger-php

composer require zircote/swagger-php

swagger-php提供了命令行工具，所以可以全局安装，然后把工具的路径加到PATH里去。

composer global require zircote/swagger-php

然后把zircote/swagger-php/bin 目录加到PATH里。这个东西本人用不到，就不研究了。

二、设置一个输出api文档数据的接口

a）、生成一个控制器： SwaggerController

b）、添加一个方法： getJSON()

    public function getJSON()
    {
        $swagger = \OpenApi\Generator::scan([app_path('Http/Controllers/')]);
        return response()->json($swagger, 200);
    }

有的文章里写 \Swagger\scan()，但我这里报错，说找不到这个类。查了官方文档，要用 \OpenApi\Generator::scan()。有可能是新版本做了修改。

c）、设置路由

api.php 或者 web.php都行，路径不同而已。本人选择api.php。所以访问路径要加个前缀：/api。

Route::group(['prefix' => 'swagger'], function () {
    Route::get('json', [\App\Http\Controllers\SwaggerController::class, 'getJSON']);
});

d）、测试访问

访问 http://localhost:8000/api/swagger/json 如果看到页面正常输出json，说明配置成功了。不然就按错误提示一项项去修改吧。

三、使用

GET方法

    /** 
     * @OA\Get(
     *     tags={"数据管理"},
     *     summary="数据查询",
     *     path="/api/data/search",
     *     @OA\Response(response="200", description="Display a listing of projects."),
     *     @OA\Parameter(
     *         description="数据名称",
     *         in="query",
     *         name="name",
     *         required=false,
     *         @OA\Schema(type="string"),
     *     ),
     *     @OA\Parameter(
     *         description="状态",
     *         in="query",
     *         name="status",
     *         required=false,
     *         @OA\Schema(type="integer"),
     *     ),
     *     @OA\Parameter(
     *         description="每页记录数",
     *         in="query",
     *         name="page-size",
     *         required=false,
     *         @OA\Schema(type="integer"),
     *     ),
     *     @OA\Parameter(
     *         description="当前页码",
     *         in="query",
     *         name="current-page",
     *         required=false,
     *         @OA\Schema(type="integer"),
     *     ),
     * )
     */

这里面:

in 表示该参数出现在哪里。 query的话就是用&拼在url后面; path 类似于 /api/data/search/{param} ; header就是包含在 request header里；cookie 自然是放在cookie里。

这个版本里formData, body这些都没有了。

required 看名字就知道 true是必填项，false是选填项。

POST方法

    /** 
     * @OA\Post(
     *     tags={"数据管理"},
     *     summary="添加数据",
     *     path="/api/data",
     *     @OA\Response(response="200", description="Display a listing of projects."),
     *     @OA\RequestBody(
     *         @OA\MediaType(
     *             mediaType="x-www-form-urlencoded",
     *             @OA\Schema(
     *                 ref="#/components/schemas/DataModel",
     *             ),
     *         ),
     *     ),
     * )
     */

因为本人的前端代码post都是表单提交，所以这里的post方法要用@OA\RequestBody。

@OA\Parameter是参数，是可以放到url上，但是post的表单提交，数据是不出现在url上的。

@OA\MediaType 这个: x-www-form-urlencoded 表单提交；application/json 提交json格式的数据；multipart/form-data 文件上传；

     *             @OA\Schema(
     *                 ref="#/components/schemas/DataModel",
     *             ),

这个是关联到一个已经定义好的schema上，省得使用相同数据的每个接口注释里都写一遍。

这里也可以单独写：

 * @OA\Schema(
 *   required={"name", "code"},
 *   @OA\Property(property="name", type="string", title="姓名", description="这是姓名"),
 *   @OA\Property(property="code", type="string", title="代码", description="这是代码"),
 *   @OA\Property(property="phone", type="string", title="电话", description="这是电话"),
 * ),

上面这样，有多少个参数就写多少个@OA\Property。

这里的required是个数组，写在里面的都是必填项。

其它方法都差不多，以后有用到了再记录。

四、显示swagger ui

下载swagger ui的代码： https://github.com/swagger-api/swagger-ui/releases

解压后，把目录里的dist目录，复制到laravel的public目录下面，改名为swagger-ui。文件名随便取，不冲突就行。

找开这个swagger-ui目录下的swagger-initializer.js，内容大概如下：

window.onload = function() {
  //<editor-fold desc="Changeable Configuration Block">
  // the following lines will be replaced by docker/configurator, when it runs in a docker-container
  window.ui = SwaggerUIBundle({
    url: "/api/swagger/json",
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  });
  //</editor-fold>
};

主要是改 url这项。改成前面设的路由地址。这里是 "/api/swagger/json"。

完成后访问 http://localhost:8000/swagger-ui/ 就能看到swagger形成的api文档了。

到此这篇关于PHP使用Swagger生成好看的API文档的文章就介绍到这了,更多相关PHP Swagger内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:

相关文章

  • PHP安全下载文件的方法

    PHP安全下载文件的方法

    这篇文章主要介绍了PHP安全下载文件的方法,涉及PHP文件的编码设置,转换,判断及下载的相关技巧,需要的朋友可以参考下
    2016-04-04
  • CodeIgniter与PHP5.6的兼容问题

    CodeIgniter与PHP5.6的兼容问题

    这篇文章主要介绍了CodeIgniter与PHP5.6的兼容问题的处理方法，有需要的小伙伴可以参考下。
    2015-07-07
  • PHP错误提示的关闭方法详解

    PHP错误提示的关闭方法详解

    关闭PHP错误脚本提示是程序上线了必须做的一件事情，就是不管程序怎么报错我们都不能让错误日志在服务器上给大家看到，下面我来总结两种关闭PHP错误脚本提示的具体方法
    2013-06-06
  • php限制ip地址范围的方法

    php限制ip地址范围的方法

    这篇文章主要介绍了php限制ip地址范围的方法,涉及php操作IP地址的技巧,非常具有实用价值,需要的朋友可以参考下
    2015-03-03
  • PHP中比较两个对象的几种方式小结

    PHP中比较两个对象的几种方式小结

    在PHP中,比较两个对象并不是一件直接明了的事情,因为对象之间的比较通常依赖于它们的属性和状态,而这些属性和状态可能非常复杂且多样化,本文给大家总结了PHP中比较两个对象的几种方式,需要的朋友可以参考下
    2024-09-09
  • php版微信公众号接口实现发红包的方法

    php版微信公众号接口实现发红包的方法

    这篇文章主要介绍了php版微信公众号接口实现发红包的方法,结合实例形式分析了php版微信公众号实现发红包的接口调用方法与相关使用注意事项,需要的朋友可以参考下
    2016-10-10
  • windows环境下php配置memcache的具体操作步骤

    windows环境下php配置memcache的具体操作步骤

    本篇文章是对windows环境下php配置memcache的具体操作步骤进行了详细的分析介绍，需要的朋友参考下
    2013-06-06
  • PHP中检索字符串的方法分析【strstr与substr_count方法】

    PHP中检索字符串的方法分析【strstr与substr_count方法】

    这篇文章主要介绍了PHP中检索字符串的方法,结合实例形式分析了strstr与substr_count函数的功能与具体使用技巧,需要的朋友可以参考下
    2017-02-02
  • PHP获取表单数据与HTML嵌入PHP脚本的实现

    PHP获取表单数据与HTML嵌入PHP脚本的实现

    下面小编就为大家带来一篇PHP获取表单数据与HTML嵌入PHP脚本的实现。小编觉得挺不错的，现在就分享给大家，也给大家做个参考。一起跟随小编过来看看吧
    2017-02-02
  • 利用PHPExcel实现Excel文件的写入和读取

    利用PHPExcel实现Excel文件的写入和读取

    本篇文章主要介绍了利用PHPExcel实现Excel文件的写入和读取的相关知识。具有很好的参考价值。下面跟着小编一起来看下吧
    2017-04-04

最新评论