网络编程
位置:首页>> 网络编程>> php编程>> PHP使用Swagger生成好看的API文档

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

作者:HOOLOO  发布时间:2023-05-25 09:56:30 

标签:PHP,Swagger,API,文档

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文档了。

来源:https://blog.csdn.net/HOOLOO/article/details/128990525

0
投稿

猜你喜欢

  • 用window.open打开的窗口中,有时候session变量会丢掉,给asp编程带来的一定的麻烦。用参数传递解决它:<DIV&nbs
  • 八月的UCDChina书友会主题是“信息分类和方法”,在会场中的内容是不足以简单的概述的,而这次交流至少对于分类、属性、关键词与Tag的定义
  • MySQL内部复制功能是建立在两个或两个以上服务器之间,通过设定它们之间的主-从关系来实现的。其中一个作为主服务器,其它的作为从服务器。本节
  •     用QQ聊过天的朋友都对它的自动隐藏窗口功能爱不释手,它可以使窗口显得清爽整洁而且富有动感,笔者的几个朋
  • MySQL是一个非常流行的小型关系型数据库管理系统,2008年1月16号被Sun公司收购。目前MySQL被广泛地应用在Internet上的中
  • 以前在网上看到的最简单的拖动对象的代码,忘记作者叫什么了。原始代码在IE下有些小问题,并且声明了文档类型为xhtml 1.0后,在FF等非I
  • 安装 SQL2000 时,系统经常会提示:操作被挂起,要求重新启动计算机,如图1: 图1重新启动后,再次安装时问题仍然存在。解决办
  • 两列布局的定宽自适应已经详解了,三列浮动中有两列定宽一列自适应的也详解了,那么该说说三列浮动中两列自适应一列定宽的布局了。中间定宽,左右两侧
  •  1. 得到安全字符串,在查询中使用,过滤单引号。Function Get_SafeStr(str)  &nb
  • 这次我们讨论的是,区分有单选框的选项和普通的选项~~乍听起来,可能不太理解我说了什么,下面举个例子先~~1、标签的单选~~例如QQ秀的支付流
  • chat.html <html> <head><title>asp之家-简单聊天&l
  • 本文介绍了asp编程中使用数组的各种方法,并给出了详细的asp实例代码方便大家理解。asp中数组的定义Dim MyArray My
  • 什么是CSS Sprites?“Sprite”(精灵)这个词在计算机图形学中有它独特的定义,由于游戏、视频等画质越来越高,必须有一种技术可以
  • 看一个网站其实就好比品评一个美女。一看长相,我们很多时候关注的是视觉,比如老板经常会说,你做几个页面让我看看!二看身材,也有很多关注标准和s
  • 在某些情况下,比如自动补全(auto complete)的输入框中,需要使用keyup事件来监听键盘的输入以迅速作出回应。关键在于keyup
  • 1.删除所有的目录,只保留datasharebin2.删除BIN下面除以下三个文件之外的所有文件:libmysql.dll(MYSQL5中的
  • phpMyAdmin是一个用PHP编写的,可以通过互联网控制和操作MySQL。通过phpMyAdmin可以完全对数据库进行操作,例如建立、复
  • 在html 5增加了新元素header、footer,测试过发现IE不能解析html 5新增的元素。代码如下:<!DOCTYPE ht
  • PERCONA PERFORMANCE CONFERENCE 2009上,来自雅虎的几位工程师带来了一篇”Efficient Paginat
  • Opera所属:挪威Opera Software ASA公司渲染引擎:自家的PrestoOpera起初是一款挪威Oper
手机版 网络编程 asp之家 www.aspxhome.com