Laravel使用 Swagger

一、Swagger 基础

1、 什么是Swagger

Swagger 是一个基于 Open Api 规范的 API 管理工具,通过项目注解的形式自动构建 API 文档,拥有在线调试的功能。提供了多语言的客户端,laravel 中也有相应的扩展包。

二、Swagger 接入

1,用compser导入l5-swagger包

composer require "darkaonline/l5-swagger"

2,生成配置及初始化文件

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

执行上述命令后,config下面会生成文件l5-swagger.php

Resources/views下面也会生成vendor文件夹

3,注册swagger

打开config/app.php,在providers数组中添加:

 \L5Swagger\L5SwaggerServiceProvider::class

4,配置swagger

defaults>paths>excludes:

这个参数用来指定在执行 php artisan l5-swagger:generate 时,需要忽略的文件。

scanOptions>pattern:

用来配置要扫描并生成文档的文件类型。

示例:

'defaults' => [ 'paths' => [ 'excludes' => [ 'App\Http\Controllers\Api\Helpers\ExceptionReport', ], ], 
], 'scanOptions' => [ 'pattern' => ['*Controller.php', '*Schema.php'], 
], 

5,生成swagger文档的方式

php artisan l5-swagger:generate

这个每次注释更新之后,都需要执行一次命令来重新生成api文档,

在.env文件下面配置L5_SWAGGER_GENERATE_ALWAYS=true

配置后,无需手动生成api文档,直接访问api文档地址即可

6,访问api文档

    访问地址:域名/api/documentation

    host比如下图这里的api.apidoc.com:本地配置的域名指向项目public这个路径

三,注解介绍


由于 Swagger 是采用注解的形式进行文档生成,需要按照既定的规则去编写注解,这里只提供一些重要的信息

API 基础信息
title:API 名称
version:API 版本
description:API 描述
@OA\Contact:联系方式
@OA\License:许可协议

请求
@OA\Get | @OA\Post:请求类型
path:请求URI
tag:归纳相同标签的接口
summary:接口概要
description:接口描述
operationId:接口ID,全局唯一
@OA\Parameter:接收的参数是来自requestHeader中,即请求头。GET、\POST都适用
@OA\RequestBody:接收的参数是来自requestBody中,即请求体。主要用来接收前端传递给后端的json字符串中的数据的,所以只能发送POST请求

匹配path中的数值则 in path 查询 in query

这里是支持多文件上传,删除一个就是单文件上传

    /**
     * @OA\Post(summary="上传文件",path="/api/upload/file/{type}",tags={"Upload"},description="上传文件",
     *     security={{"Bearer":{} }},
     *     @OA\Parameter(name="type",in="path",required=true,description="类型"),
     *     @OA\RequestBody(
     *         @OA\MediaType(
     *             mediaType="multipart/form-data",
     *             @OA\Schema(
     *                 @OA\Property(property="file",type="file",description="文件"),
     *                 @OA\Property(property="file2",type="file",description="文件2")
     *             )
     *         )
     *     ),
     *     @OA\Response(response="200",description="获取成功",
     *     @OA\MediaType(mediaType="application/json",
     *             @OA\Schema(
     *                 @OA\Property(property="img_url",description="路径",type="string"),
     *                 @OA\Property(property="original_name",description="原始名称",type="string"),
     *             )
     *         )
     *      )
     * )
     */
    public function postUploadFile($case){
        $file = $this->request->file('file');
         //逻辑
    }
 

响应
@OA\Response:响应信息
response:响应的 http 状态码
description:响应描述
@OA\MediaType:响应体
mediaType:返回格式
@OA\Schema:定义响应体内的数据
@OA\Property:定义属性字段(id),数据类型(string),字段描述(description)
@OA\JsonContent:因为现在接口通常采用 json 通讯,所以可以直接定义 json 响应格式
ref:指定可复用的注解模块,TestApi 为模块ID,全局唯一
@OA\Schema:可复用注解模块,内部可嵌套 Schema

四,附加,更加详细的注解说明可以参考文档:

https://learnku.com/laravel/t/7430/how-to-write-api-documents-based-on-swagger-php

Laravel Swagger 使用完整教程-CSDN博客

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

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

第21~22周Java主流框架入门-Spring 3.SpringJDBC事务管理

Spring JDBC模块与事务管理课程总结 1. 课程介绍 本课程主要讲解Spring框架中的JDBC模块及其事务管理的相关内容,重点包括以下三个方面: Spring JDBC模块及核心对象JDBC Template的使用 通过学习如何使用Spring JDBC模块,了解JDBC Template…

Vue3 学习笔记(一)Vue3 介绍及环境部署

一、Vue.js 简介 1、Vue.js 是什么? Vue.js(读音 /vjuː/, 类似于 view) 是一套构建用户界面的渐进式框架。Vue 只关注视图层, 采用自底向上增量开发的设计。Vue 的目标是通过尽可能简单的 API 实现响应的数据绑定和组合的视图组件…

【ARM】ARM架构参考手册_Part B 内存和系统架构(2)

目录 2.1 关于系统控制协处理器 2.2 寄存器 2.1 关于系统控制协处理器 所有标准内存和系统设施都由协处理器15(CP15)控制,因此它被称为系统控制协处理器。有些设施也使用其他控制方法,这些方法在描述这些设施的章节中有描述。例…

【Mysql】-锁,行级锁

Mysql mysql中的行锁 在 MySQL 的 InnoDB 存储引擎中,行级锁通常是加在索引上的,而不是直接加在数据行上。这种机制是基于索引的锁定策略,具体来说: 主键索引:如果查询更新使用了主键进行查找,InnoDB 会直…

性能工具之JMeter 通过Java API生成 BeanShell PreProcessor 脚本

文章目录 一、前言二、实现代码三、代码示例四、最后 一、前言 对于上一篇文章(性能工具之 HAR 格式化转换JMeter JMX 脚本文件)还是有点问题。大家在使用的情况需要注意。 如果多个接口相同 path 路径且不同参数进行查询如: 上面接口如果…

【力扣 | SQL题 | 每日3题】力扣2988,569,1132,1158

1 hard 3mid,难度不是特别大。 1. 力扣2988:最大部门的经理 1.1 题目: 表: Employees ---------------------- | Column Name | Type | ---------------------- | emp_id | int | | emp_name | varchar | | de…

【前端】如何制作一个自己的网页(15)

有关后代选择器的具体解释&#xff1a; 后代选择器 后代选择器使用时&#xff0c;需要以空格将多个选择器间隔开。 比如&#xff0c;这里p span&#xff0c;表示只设置p元素内&#xff0c;span元素的样式。 <style> /* 使用后代选择器设置样式 */ p span { …

java--多态(详解)

目录 一、概念二、多态实现的条件三、向上转型和向下转型3.1 向上转型3.2 向下转型 四、重写和重载五、理解多态5.1练习&#xff1a;5.2避免在构造方法中调用重写的方法&#xff1a; 欢迎来到权权的博客~欢迎大家对我的博客提出指导这是我的博客主页&#xff1a;点击 一、概念…

Java毕业设计 基于SpringBoot发卡平台

Java毕业设计 基于SpringBoot发卡平台 这篇博文将介绍一个基于SpringBoot发卡平台&#xff0c;适合用于Java毕业设计。 功能介绍 首页 图片轮播 商品介绍 商品详情 提交订单 文章教程 文章详情 查询订单  查看订单卡密 客服   后台管理 登录 个人信息 修改密码 管…

API接口的未来展望:构建更加智能、安全、高效的数字世界

一、引言 随着信息技术的飞速发展&#xff0c;应用程序编程接口&#xff08;API&#xff09;已成为现代软件开发的核心组成部分。API作为不同系统之间的桥梁&#xff0c;使得数据、功能和服务能够在各种平台和设备之间无缝流动。在这个数字化时代&#xff0c;API接口的未来展望…

javascript对象介绍

1. 什么是对象&#xff1f; 在 JavaScript 中&#xff0c;对象是一个无序的键值对集合&#xff0c;可以用来存储数据和功能。对象可以包含原始值、函数&#xff08;方法&#xff09;以及其他对象&#xff0c;是构建复杂数据结构和实现面向对象编程的基础。 2. 创建对象 2.1 …

Selenium爬虫技术:如何模拟鼠标悬停抓取动态内容

介绍 在当今数据驱动的世界中&#xff0c;抓取动态网页内容变得越来越重要&#xff0c;尤其是像抖音这样的社交平台&#xff0c;动态加载的评论等内容需要通过特定的方式来获取。传统的静态爬虫方法难以处理这些由JavaScript生成的动态内容&#xff0c;Selenium爬虫技术则是一…

字典如何与选择器一起使用

背景&#xff1a;开发过程中会遇到某些字段需要做成下拉框。如下图&#xff1a; 组件 | Element里有select选择器这个组件可以实现下拉框的效果 我们可能会想到创一个辅助表来存储这些下拉数据像这样 这样虽然能实现&#xff0c;但是在实际开发中是不合理的&#xff0c;如果有…

个税自然人扣缴客户端数据的备份与恢复(在那个文件夹)

一&#xff0c;软件能够正常打开&#xff0c;软件中的备份与恢复功能 1&#xff0c;备份 您按照下面的方法备份一下哦~ 进入要备份的自然人软件&#xff0c;点击左侧系统设置→→系统管理→→备份恢复&#xff1b; 在备份设置里&#xff0c;点击“备份到选择路径”&#xff0c;…

WebGL编程指南 - 颜色与纹理续

设置纹理坐标&#xff08;initVertexBuffers()&#xff09; 从缓冲区到 attribute 变量的流程&#xff1a; // 顶点坐标 function initVertexBuffers(gl) {// 数据准备let verticesTexCoords new Float32Array([// 顶点坐标&#xff0c;纹理坐标-0.5, 0.5, 0.0, 1.0, -0.5, …

图像异常检测评估指标-分类性能

图像异常检测评估指标-分类性能 1. 混淆矩阵 混淆矩阵包括4个用于衡量分类算法性能的基本数值 四个字母代表的含义是&#xff1a;P&#xff08;Positive&#xff09;代表算法将样本预测为正类&#xff0c;N&#xff08;Negative&#xff09;代表算法将样本预测为负类&#xf…

<a-table>行数据增加点击事件并获取点击行的数据+自定义button按事件

先看代码&#xff1a; 在 Ant - Design - Vue 的<a - table>组件中&#xff0c;通过customRow属性可以为表格的每一行添加自定义的行为和样式。当设置customRow为一个返回包含onClick函数的对象的函数时&#xff0c;实际上是在为每一行添加一个点击事件监听器。 在a-tabl…

Java学习Day50:唤醒八戒(Excel相关)

1.批量导入Excel数据 1.实现模板下载 <el-card class"box-card"> <div class"boxMain"> <el-button style"margin-bottom: 20px;margin-right: 20px" type"primary" click"downloadTemplate()">模板下载…

ST7789读取ID错误新思路(以STC32G为例)

1.前言 前两天刚把ST7789写入搞定&#xff0c;这两天想折腾一下读取。最开始是读ID&#xff0c;先是用厂家送的程序&#xff0c;程序里面用的是模拟I8080协议&#xff0c;一切正常。后来我用STC32G的内置LCM模块&#xff0c;发现读取不出来。更神奇的是ID读不出来&#xff0c;…

达梦数据库DEXP/DIMP逻辑备份还原

1、概念 逻辑备份还原是对数据库逻辑组件&#xff08;如表、视图和存储过程等数据库对象&#xff09;的备份还原。逻辑导出&#xff08;dexp&#xff09;和逻辑导入&#xff08;dimp&#xff09;是 DM 数据库的两个命令行工具&#xff0c;分别用来实现对 DM 数据库的逻辑备份和…