L5 Swagger 使用说明
网上看了看,关于这个扩展介绍很少。今天工作恰好用到,研究了一下,觉得有必要分享一下。
一、 简介:
这个包是Swagger-php和Swagger-ui的封装,适用于Laravel5。
二、版本要求
Laravel> = 5.1
三、安装
Laravel |
Swagger UI |
OpenAPI规范兼容性 |
L5 安装命令 |
5.1.x版 |
2.2 |
1.1,1.2,2.0 |
php composer require "darkaonline/l5-swagger:~3.0" |
5.2.x |
2.2 |
1.1,1.2,2.0 |
php composer require "darkaonline/l5-swagger:~3.0" |
5.3.x |
2.2 |
1.1,1.2,2.0 |
php composer require "darkaonline/l5-swagger:~3.0" |
5.4.x版本 |
2.2 |
1.1,1.2,2.0 |
php composer require "darkaonline/l5-swagger:~4.0" |
5.4.x版本 |
3 |
2.0 |
php composer require "darkaonline/l5-swagger:5.4.*" |
5.5.X |
3 |
2.0 |
php composer require "darkaonline/l5-swagger:5.5.*" |
或在composer.json中添加"darkaonline/l5-swagger": "~3.0"(以5.1为例),再执行composer update。
四、配置
打开config/app.php注册一个门面,5.5以上的版本不用。
加入这一行providers节:L5Swagger \ L5SwaggerServiceProvider :: class,
运行php artisan l5-swagger:publish 这一步的意义是将包的内容发布。也可以使用php artisan l5-swagger:publish-config(生成配置文件),php artisan l5-swagger:publish-assets(生成根目录文件夹),php artisan l5-swagger:publish-views(生成视图层文件夹)分别发布。执行之后会在根目录和视图层生成一个vendor文件夹;并在config/下生成一个l5-swagger.php的文件,这里重点说一下这个文件,在这里可以指定标题,访问路由,项目路由,生成文件即生成文件路由。可以在.env中设置环境变量如token,key等值。
注:如果在你的项目中你不需要资源文件可将其填入.gitignore中。如./public/vendor/l5-swagger,./resources/views/vendor/l5-swagger等文件每次请求都会生成一次。
五、使用
使用phpartisan l5-swagger:generate生成文档,此时会在storage/api-docs,生成一个api-docs.json的文件,一会每次生成都会覆盖此文件。如果需要开启自动生成,可在配置文件或.env文件中设置generate_always
参数为true
。这个时候访问你的项目域名+
/ api / documentation。你会看到,如下页面:
接下来我们建立一个swagger控制器,写入如下测试数据:
<?php
namespace App\Http\Controllers;
use Swagger\Annotations\Info;
/**
* @Info(
* title="My title",
* version="v1.0.0"
* )
*/
class SwaggerController extends Controller
{
/**
* 假设是项目中的一个API
*
* @SWG\Get(path="/swagger/my-data",
* tags={"project"},
* summary="拿一些神秘的数据",
* description="请求该接口需要先登录。",
* operationId="getMyData",
* produces={"application/json"},
* @SWG\Parameter(
* in="formData",
* name="reason",
* type="string",
* description="拿数据的理由",
* required=true,
* ),
* @SWG\Response(response="default", description="操作成功")
* )
*/
public function getMyData()
{
}
}
标红部分@SWG \ Info是必需的,这里声明了你的版本号,负责会报错。生成文件看到如下:
接下来可设置中文,默认展开,取消默认图标:
设置中文:
打开resources/views/vendor/index.blade.php
找的这一行:
// ...
<!-- Some basic translations -->
<!--<script src='lang/translator.js' type='text/javascript'></script>-->
<!--<script src='lang/ru.js' type='text/javascript'></script>-->
<!-- <script src='lang/en.js' type='text/javascript'></script> -->
// ...
改为:
<!-- Some basic translations -->
<scriptsrc='{{config('l5-swagger.paths.assets_public')}}/lang/translator.js'type='text/javascript'></script>
<scriptsrc='{{config('l5-swagger.paths.assets_public')}}/lang/zh-cn.js'type='text/javascript'></script>
默认展开:
onFailure: function(data) {
console.log("Unableto Load SwaggerUI");
},
docExpansion: {!! isset($docExpansion) ? '"' . $docExpansion .'"' : '"none"' !!}
这里设置docExpansion: "none",
去掉error:
window.swaggerUi =
newSwaggerUi({
// ...
validatorUrl:
null,
//添加这个配置
});
接下来就可以正常使用了。
个人公众号谢谢各位老铁支持
L5 Swagger 使用说明的更多相关文章
- Swagger 生成 PHP API 接口文档
Swagger 生成 PHP API 接口文档 Lumen微服务生成Swagger文档 1.概况 有同学反馈写几十个接口文档需要两天的工作量, 随着多部门之间的协作越来越频繁, 维护成本越来越高, 文 ...
- swagger 生成 api 文档 html
https://cloud.tencent.com/developer/article/1332445 使用Swagger2Markup实现导出API文档 飞狗发表于专注于主流技术和业务订阅 2.4K ...
- .NET Core的响应式框架,基于Ace Admin框架菜单导航,Bootstrap布局,fontAwesome图标,内嵌Iframe用EasyUI做数据绑定,动态配置列表,动态配置表单
netnrf 响应式框架 用于快速开发的响应式框架 演示:https://rf2.netnr.com v3.x 前端采用 jQuery + Bootstrap + EasyUI + AceAdmin ...
- SpringMVC 中配置 Swagger 插件.
一.简介 Swagger的目标是为REST API定义一个与语言无关的标准接口,允许用户发现和理解计算机服务的功能,而无需访问源代码.当通过Swagger正确定义时,用户可以用最少量的实现逻辑理解远程 ...
- Spring Boot 集成 Swagger,生成接口文档就这么简单!
之前的文章介绍了<推荐一款接口 API 设计神器!>,今天栈长给大家介绍下如何与优秀的 Spring Boot 框架进行集成,简直不能太简单. 你所需具备的基础 告诉你,Spring Bo ...
- 记Asp.Net Core Swagger 使用 并带域接口处理
引用作者原话:Asp.Net的WebApi中使用Swagger作为说明和测试的页面是非常不错的,比起WebApiTestClient来至少在界面上的很大的提升.但是使用Swagger时如果只是一般的控 ...
- 中小研发团队架构实践之生产环境诊断工具WinDbg 三分钟学会.NET微服务之Polly 使用.Net Core+IView+Vue集成上传图片功能 Fiddler原理~知多少? ABP框架(asp.net core 2.X+Vue)模板项目学习之路(一) C#程序中设置全局代理(Global Proxy) WCF 4.0 使用说明 如何在IIS上发布,并能正常访问
中小研发团队架构实践之生产环境诊断工具WinDbg 生产环境偶尔会出现一些异常问题,WinDbg或GDB是解决此类问题的利器.调试工具WinDbg如同医生的听诊器,是系统生病时做问题诊断的逆向分析工具 ...
- 特别好用的swagger ui 封装
Swagger简单介绍 Swagger是一个Restful风格接口的文档在线自动生成和测试的框架 官网:http://swagger.io 官方描述:The World’s Most Popular ...
- 【swagger】2.swagger提供开发者文档--返回统一格式篇【spring mvc】【spring boot】
接着上一篇来说, 不管正常返回结果还是后台出现异常,应该返回给前台统一的响应格式. 所以这一篇就为了应对解决这个问题. ======================================== ...
随机推荐
- 配置 setting镜像在nexus私服上下载
在你的本地仓库上 setting文件中配置,一旦nexus服务关闭是无法下载的 1 配置nexus镜像 <mirror> <id>central1</id> < ...
- MySQL——索引
MySQL索引的概念 MySQL官方对索引的定义为:索引(Index)是帮助MySQL高效获取数据的数据结构,通俗来讲索引就好比书本的目录,加快数据库的查询速度. 举个简单的例子,见下图: 注意:此例 ...
- CentOS 6、CentOS7 防火墙开放指定端口
当我们在CentOS服务器中装了一些开发环境(如 tomcat.mysql.nginx 等...)时,希望能从外界访问,就需要配置防火墙对指定端口开放. CentOS 6.51.开放指定端口/sbin ...
- RocketMQ 主从同步
RocketMQ 的主和从一直在使用 nio 进行数据同步: master master 监听端口 org.apache.rocketmq.store.ha.HAService.AcceptSocke ...
- lua源码学习篇二:语法分析
一步步调试,在lparser.c文件中luaY_parser函数是语法分析的重点函数,词法分析也是在这个过程中调用的.在这个过程中,用到一些数据结构,下面会详细说. Proto *luaY_parse ...
- 跨 Appdomain 对象共享
using System; using System.Collections.Generic; using System.Linq; using System.Web; using System.We ...
- 转:【开源必备】常用git命令
原文:https://zhuanlan.zhihu.com/p/25868120 [开源必备]常用git命令 [已重置] 如今在技术领域,码农们习惯了开源,也离不开免费开源的代码,轻松获取代码,不 ...
- IDEA神器
破解 路径:添加-javaagent:JetbrainsCrack-2.7-release-str.jar的路径 例-javaagent:D:\Program Files\JetBrains\Inte ...
- [Web 前端] 023 js 的流程控制、循环和元素的获取、操作
1. Javascript 流程控制 用于"基于不同条件执行不同的动作"的场合 1.1 if 语句 三种形式 // 第一种 if... // 第二种 if... else ... ...
- uboot环境变量
一. uboot运行时环境变量分布 1.1. 环境变量有2份,一份在Flash中,另一份在DDR中.uboot开机时一次性从Flash中读取全部环境变量到DDR中作为环境变量的初始化值,然后使用过程中 ...