Laravel swagger接口文档生成和管理

Laravel swagger接口文档生成和管理

接口开发随着时间推移接口会越来越多,随着多部门之间的协作越来越频繁, 维护成本越来越高, 文档的可维护性越来越差, 需要一个工具来管理这些接口的文档, 并能够充当mock server给调用方使用

这里推荐swagger生成和管理接口文档,下面介绍基于laravel项目的swagger使用

福利彩蛋:没有好玩的 API 接口?上百款免费接口等你来,免费 API,免费 API 大全

安装swagger

    
    //安装
    composer require darkaonline/l5-swagger
    

laravel >= 5.5

    php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
    php artisan l5-swagger:generate

laravel < 5.5

    php artisan l5-swagger:publish
    php artisan l5-swagger:publish-config
    php artisan l5-swagger:publish-assets
    php artisan l5-swagger:publish-views
    
    php artisan l5-swagger:generate

注意:在运行 php artisan l5-swagger:generate 命令之前,请确保在app目录下存在@OA\Info注解和 且至少定义一个@OA\Get 注解(接口) 否则会异常:


//这是基本信息

/**
 * @OA\Info(
 *      version="1.0.0",
 *      title="L5 OpenApi",
 *      description="L5 Swagger OpenApi description",
 *      @OA\Contact(
 *          email="darius@matulionis.lt"
 *      ),
 *     @OA\License(
 *         name="Apache 2.0",
 *         url="http://www.apache.org/licenses/LICENSE-2.0.html"
 *     )
 * )
 */
 
 //这是get接口
/**
  * @OA\Get(
  *   path="/api/users/{user_id}",
  *   summary="根据 ID 获取用户信息",
  *   tags={"用户管理"},
  *   @OA\Parameter(
  *     name="user_id",
  *     in="path",
  *     required=true,
  *     description="用户 ID",
  *     @OA\Schema(
  *        type="string"
  *     )
  *   ),
  *   @OA\Response(
  *     response=200,
  *     description="用户对象",
  *     @OA\JsonContent(ref="#/components/schemas/UserModel")
  *   )
  * )
  */
  
  //UserModel定义
  
  /**
 * @OA\Schema(
 *      schema="UserModel",
 *      required={"username", "age"},
 *      @OA\Property(
 *          property="username",
 *          type="string",
 *          description="用户名称"
 *      ),
 *      @OA\Property(
 *          property="age",
 *          type="int",
 *          description="年龄"
 *      )
 * )
 */

全局鉴权:注解

/**
 * @OA\SecurityScheme(
 *     type="oauth2",
 *     description="这里有多中校验方式:basic|apiKey|oauth2",
 *     name="Password Based",
 *     in="header|query",
 *     scheme="https",
 *     securityScheme="Password Based",
 *     @OA\Flow(
 *         flow="password",
 *         authorizationUrl="/oauth/authorize",
 *         tokenUrl="/oauth/token",
 *         refreshUrl="/oauth/token/refresh",
 *         scopes={}
 *     )
 * )
 */
 

全局鉴权:config配置全局开启(l5-swagger.php)

    'securityDefinitions' => [
        'securitySchemes' => [
            /*
             * Examples of Security schemes
            */

            'Authorization-Bearer' => [ // Unique name of security
                'type' => 'apiKey',
                // The type of the security scheme. Valid values are "basic", "apiKey" or "oauth2".
                'description' => '用户登录鉴权Token',
                'name' => 'authorization',
                // The name of the header or query parameter to be used.
                'in' => 'header',
                // The location of the API key. Valid values are "query" or "header".
            ],
        ]
    ]

鉴权参数

参数含义
type类型 “http”, “apiKey”, “oauth2”, “openIdConnect”
name名称
in需要API密钥的位置 值为 query、header
flowOAuth2安全方案使用的流 值为:“implicit”、“password”、“application”或“accesscode”
authorizationUrlOAuth2授权URL
scopesOAuth2安全方案的可用范围

问题

如果在使用中遇到了Authorize:apiKey header模式情况下,token未通过header进行请求传递的话请参照修复

修改:/resource/views/vendor/l5-swagger/index.blade.php,主动添加token到头部

  window.ui = ui

  ui.getConfigs().requestInterceptor = function (request) {
    if (ui.authSelectors.authorized().size){
      var authObject = ui.authSelectors.authorized()._root.entries[0];
      var securityConfig = authObject[1]._root.entries[1][1]._list._tail.array;
      if (securityConfig[0][1] === 'apiKey' && securityConfig[3][1] === 'header') {
        var token = authObject[1]._root.entries[2][1];
        if (authObject[0] === 'Bearer' && !token.startsWith('Bearer ')){
          token = 'Bearer ' + token;
        }
        request.headers[securityConfig[2][1]] = token;
      }
    }
    request.headers['X-CSRF-TOKEN'] = '{{ csrf_token() }}';
    return request;
  } 

演示

运行完php artisan l5-swagger:generate 命令后就可以通过浏览器查看接口文档(访问/api/documentation: 当然这个地址可以在l5-swagger.php配置文件中进行修改)

image.png
福利彩蛋:没有好玩的 API 接口?上百款免费接口等你来,免费 API,免费 API 大全

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:/a/768906.html

如若内容造成侵权/违法违规/事实不符,请联系我们进行投诉反馈qq邮箱809451989@qq.com,一经查实,立即删除!

相关文章

硅纪元视角 | 1 分钟搞定 3D 创作,Meta 推出革命性 3D Gen AI 模型

在数字化浪潮的推动下&#xff0c;人工智能&#xff08;AI&#xff09;正成为塑造未来的关键力量。硅纪元视角栏目紧跟AI科技的最新发展&#xff0c;捕捉行业动态&#xff1b;提供深入的新闻解读&#xff0c;助您洞悉技术背后的逻辑&#xff1b;汇聚行业专家的见解&#xff0c;…

Arthas实战(2)- OOM问题排查

一、 准备测试应用 新建一个 SpringBoot应用&#xff0c;写一段有 OOM bug 的代码&#xff1a; RestController RequestMapping public class JvmThreadController {List<TestWrapper> memoryList new ArrayList<>();GetMapping("/test")public Strin…

Element 的 el-table 表格实现单元格合并

html 部分 <template><div class"index-wapper"><el-table :data"tableData" :span-method"objectSpanMethod" border><el-table-column v-for"(item, index) in tableHeader" :key"index" :prop&quo…

【C语言】auto 关键字

在C语言中&#xff0c;auto关键字用于声明局部变量&#xff0c;但它的使用已经变得很少见。事实上&#xff0c;从C99标准开始&#xff0c;auto关键字的默认行为就是隐含的&#xff0c;因此在大多数情况下无需显式使用它。 基本用法 在C语言中&#xff0c;auto关键字用于指定变…

五粮液:稳,还稳得住吗?

前有“酱香”茅台一骑绝尘&#xff0c;后有“清香”汾酒21%的增速虎视眈眈。 在新的股东大会上&#xff0c;管理层把“稳”字说了近30次。 就问白酒二哥——五粮液&#xff0c;你还稳得住吗&#xff1f; 近期&#xff0c;白酒大哥茅台因跌价吸引各方关注&#xff0c;但在这一…

【目标检测】DN-DETR

一、引言 论文&#xff1a; DN-DETR: Accelerate DETR Training by Introducing Query DeNoising 作者&#xff1a; IDEA 代码&#xff1a; DN-DETR 注意&#xff1a; 该算法是在DAB-DETR基础上的改进&#xff0c;在学习该算法前&#xff0c;建议掌握DETR、DAB-DETR等相关知识…

学习伦敦金技术分析的具体步骤是什么?

技术分析是我们分析伦敦金市场的重要工具&#xff0c;刚入市就面对时涨时跌的市场应该如何交易呢&#xff1f;投资者如果不掌握技术分析的方法&#xff0c;恐怕对这个问题会没有头绪。入场都没有&#xff0c;盈利就更加无从谈起了。而学习技术分析&#xff0c;是有不同的阶段、…

技术周总结 2024.06.24~06.30(Python并发执行shell并发执行 Spring Bean)

文章目录 一、 06.26 周三1.1&#xff09;问题01&#xff1a;怎么在mysql的命令行中查询出来 python能使用的元祖结果集1.2&#xff09;问题02&#xff1a;python中 set()是什么&#xff0c;怎么使用 二、06.27 周四2.1&#xff09;问题01&#xff1a;shell 并发执行2.2&#x…

工程文件参考——CubeMX+LL库+SPI主机 阻塞式通用库

文章目录 前言CubeMX配置SPI驱动实现spi_driver.hspi_driver.c 额外的接口补充 前言 SPI&#xff0c;想了很久没想明白其DMA或者IT比较好用的方法&#xff0c;可能之后也会写一个 我个人使用场景大数据流不多&#xff0c;如果是大批量数据交互自然是DMA更好用&#xff0c;但考…

WPF自定义模板--TreeView 实现菜单连接线

有些小伙伴说&#xff0c;在TreeView中&#xff0c;怎么每一个都加上连接线&#xff0c;进行显示连接。 代码和效果如下&#xff1a; 其实就是在原来的模板中增加一列显示线条&#xff0c;然后绘制即可 <Window x:Class"XH.TemplateLesson.TreeViewWindow"xmln…

使用EndNote在Word中插入参考文献,并编辑参考文献样式方法

一、背景 在准备中期报告时&#xff0c;学校给的是Word模板&#xff0c;习惯了Latex排版和添加参考文献的便利后&#xff0c;真不想用word写东西。 之前投《机器人》期刊&#xff08;被拒了&#xff09;和准备开题的时候也是用word写的&#xff0c;当时为方便添加参考文献和定…

C++初学者指南-3.自定义类型(第一部分)-异常

C初学者指南-3.自定义类型(第一部分)-异常 文章目录 C初学者指南-3.自定义类型(第一部分)-异常简介什么是异常&#xff1f;第一个示例用途:报告违反规则的行为异常的替代方案标准库异常处理 问题和保证资源泄露使用 RAII 避免内存泄漏&#xff01;析构函数&#xff1a;不要让异…

labview技巧——AMC框架安装

AMC工具包的核心概念是队列&#xff0c;队列是一种先进先出&#xff08;FIFO&#xff0c;First In First Out&#xff09;的数据结构&#xff0c;适用于处理并发和异步任务。在LabVIEW中&#xff0c;队列可以用于在不同VI之间传递数据&#xff0c;确保消息的有序处理&#xff0…

LT8668SXC 、LT8668SX-D 、LT8668SX三种芯片的相似与不同

一、LT8668SXC(支持eDP输出&#xff09; 定义:LT8668SXC配置在HDMI2.1标准下工作&#xff0c;最大数据速率为8Gbps。 LT8668SXC还可以配置为在Type-C输入或DP1.4a下工作&#xff0c;数据速率高达8.1Gbps。 eDP1.4b输出由8个数据通道组成&#xff0c;支持RBR (1.62Gbps)、HBR (2…

【应届应知应会】SQL常用知识点50道

SueWakeup 个人主页&#xff1a;SueWakeup 系列专栏&#xff1a;借他一双眼&#xff0c;愿这盛世如先生所愿 个性签名&#xff1a;人生乏味啊&#xff0c;我欲令之光怪陆离 本文封面由 凌七七~❤ 友情提供 目录 数据库的概念 (什么是数据库) RDBMS NOSQL 数据库的分类 …

分布式锁——基于Redis分布式锁

单机锁 服务器只有一个&#xff0c;JVM只有一个。 用synchronized加锁&#xff0c;对lock对象加锁&#xff0c;只有线程1结束&#xff0c;线程2,3才会开始。 再用uid避免一个线程多次进来。 分布式锁 真正上线时&#xff1a; 【注&#xff1a;这些服务器连接的是一个Redis集…

FreeRTOS和UCOS操作系统使用笔记

FreeRTOS使用示例 UCOS使用示例 信号量使用 信号量访问共享资源区/ OS_SEMMY_SEM; //定义一个信号量&#xff0c;用于访问共享资源OSSemCreate ((OS_SEM* )&MY_SEM, //创建信号量&#xff0c;指向信号量(CPU_CHAR* )"MY_SEM", //信号量名字(OS_SEM_CTR )1, …

STM32入门笔记(03): ADC(SPL库函数版)(2)

A/D转换的常用技术有逐次逼近式、双积分式、并行式和跟踪比较式等。目前用的较多的是前3种。 A/D转换器的主要技术指标 转换时间 分辨率 例如&#xff0c;8位A/D转换器的数字输出量的变化范围为0&#xff5e;255&#xff0c;当输入电压的满刻度为5V时&#xff0c;数字量每变化…

Google Play上架防关联,打包环境是关联因素之一还是无足轻重?

在Google Play上架应用&#xff0c;对于矩阵式上架或马甲包的开发者来说&#xff0c;防关联的处理技能是必须要精通的。想象一下&#xff0c;你辛辛苦苦开发的应用&#xff0c;因为一些看似微不足道的细节&#xff0c;比如打包环境的问题&#xff0c;就可能被谷歌无情下架或封号…

力扣双指针算法题目:移动零

1.题目 . - 力扣&#xff08;LeetCode&#xff09; 2.思路解析 这个题目的思路和“使用递归排序快速排序解决数组的排序问题”相同 class solution { public:void QuickSort(vector<int>& nums, int left, int right){if (left > right) return;int key left…