swagger UI 使用
一、What is swagger?
官方介绍:Swagger是一个规范且完整的框架,提供描述、生产、消费和可视化RESTful Web Service。
专业角度:Swagger是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。
二、Why use the swagger?
- 讲个故事:在2014年时候,我和另一个小伙伴加入到一个实验室,开始了我们漫长的应用开发之路(这也是第一次做项目)。因为只有两个人,我做后台,他做Android,分工很明确的。在一开始,我们并没有关注API相关的内容,随手拈来,我说什么,他就调用什么。当然,也没有什么API文档提供。以至于到现在,我想更新升级系统,才发现,我们写的代码是有多烂,连自己都不忍心去看的。所以说在项目开始就定一个契约,双方(前端后台)就API相关的内容,包括路径、参数、类型等达成一致,当然,这份契约并不是一旦创建就不能修改的,而且,如果一开始没有设计好,很有可能会频繁的修改。
- 作为一个很懒的码代码的猿呢,对于一些API的理解总是很模糊不清,但是,总想着能直接验证一下自己的理解就好了,而不是需要去项目写测试代码来验证自己的想法。所以说,API文档应该有直接运行的能力。而Swagger就是这样的一个东西,它可以为已有项目的生成具备执行能力的样式化API文档,这样可以极大的方便程序员对前端后台进行对接整合。
三、use the swagger
1. 开发环境介绍
- maven 3.3
- jdk 8+
- spring 4.2.5
- mybatis 3.4.1
- swagger 1.0.2
2. 在pom.xml文件中添加swagger相关依赖
<!-- swagger-mvc --><dependency><groupId>com.mangofactory</groupId><artifactId>swagger-springmvc</artifactId><version>1.0.2</version></dependency><dependency><groupId>com.fasterxml.jackson.core</groupId><artifactId>jackson-databind</artifactId><version>2.6.6</version></dependency><!-- swagger-mvc -->
3. 自定义对swagger的配置
对于swagger的配置,其实对自定义一个与swagger相关的Config类,可以通过Java编码的实现配置。代码如下:
package com.hp.common.swagger;import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.paths.SwaggerPathProvider;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;/*** * @ClassName: SwaggerConfig.java* @Description: Swagger配置类** @version: v1.1.0* @author: xiangdong* @date: Mar 16, 2017*/
public class SwaggerConfig extends WebMvcConfigurerAdapter {private SpringSwaggerConfig springSwaggerConfig;@Autowiredpublic void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {this.springSwaggerConfig = springSwaggerConfig;}/*** 链式编程 来定制API样式 后续会加上分组信息* * @return
*/@Beanpublic SwaggerSpringMvcPlugin customImplementation(){return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo()).includePatterns(".*?");}private ApiInfo apiInfo() {ApiInfo apiInfo = new ApiInfo("API接口测试平台","提供后台所有Restful接口", "www.flyeast.top","shexd1001@gmail.com", "β客栈", "www.flyeast.top");return apiInfo;}@Overridepublic void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {configurer.enable();}
}
3. 注入SwaggerConfig类
上面这段对swagger进行了基本的配置,现在需要将其注入到spring容器中,完成在程序加载之后对所有接口扫描解析的功能呢,在spring相关的配置文件中加入以下代码:
<!-- swagger配置信息 --><bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
4. 配置需要解析的接口方法
以下代码是Controller中的一个方法,@ApiOperation注解对这个方法进行了说明,@ApiParam注解对方法参数进行了说明。关于其他注解,可以查看源码或其他帮助文档;
/*** DELETE 删除用户* @return
*/@ApiOperation(value = "删除用户信息", notes = "删除用户", httpMethod = "DELETE", produces = MediaType.APPLICATION_JSON_VALUE)@RequiresPermissions("sysuser:list:delete")@RequestMapping(value = "/list/{accountId}/delete", method = RequestMethod.DELETE)@ResponseBodypublic AjaxResult delete(@PathVariable Long accountId) {systemUserService.deleteSysUser(accountId);return success(true);}
5. 对Swagger-UI进行配置
Swagger扫描解析得到的是一个json文档,所以对于用户使用不是很方便,但是通过swagger-ui,可以友好的展示解析得到的接口说明内容。
从这里 获取其所有的 dist 目录下东西放到需要集成的项目里,本文放入 src/main/webapp/目录下。
修改index.html文件,默认是从连接http://petstore.swagger.io/v2/swagger.json获取 API 的 JSON,我们需要将url值修改为http://{ip}:{port}/{projectName}/api-docs的形式,如http://localhost:8080/CloudTi/api-docs
6. 运行项目,访问URL
URL是自己在index.html中定义的URL
![](https://upload-images.jianshu.io/upload_images/3269064-c02137ab6871c3fd.jpg?imageMogr2/auto-orient/strip%7CimageView2/2/w/700)
7. 结束
作者:Xiangdong_She
链接:https://www.jianshu.com/p/f76d2c421422
來源:简书
简书著作权归作者所有,任何形式的转载都请联系作者获得授权并注明出处。
swagger UI 使用相关推荐
- ASP.NET Core 在 Swagger UI 中显示自定义的 Header Token
Swagger 是个好东西,对于前后端分离的网站来说,不仅是提高前后端开发人员沟通效率的利器,也大大方便了后端人员测试 API.有时候,API 中可能需要在 Header 中设置认证参数,比如 aut ...
- Flask 系列之 构建 Swagger UI 风格的 WebAPI
说明 操作系统:Windows 10 Python 版本:3.7x 虚拟环境管理器:virtualenv 代码编辑器:VS Code 实验 环境初始化 # 创建项目目录 mkdir helloworl ...
- Swagger UI
Swagger UI allows anyone - be it your development team or your end consumers - to visualize and inte ...
- Swagger UI 与SpringMVC的整合 II
pom.xml <!-- swagger开始 --><dependency><groupId>io.springfox</groupId><art ...
- SpringMVC+JWT+Swagger UI+RestFul
前言: 其实很早就想写这篇文章了,因为我觉得这会对很多新手有指引作用,当初自己也是瞎子过河的摸索着过来的.目前后台开发比较流行的MVC框架中使用Spring MVC还是比较多的,当然还有Spring ...
- [第二篇]如何在ASP.Net Core的生产环境中使用OAuth保护swagger ui
在我上篇文章如何在ASP.Net Core的生产环境中保护swagger ui中,我们讨论了如何使用基本身份验证来保护 swagger ui. 使用 OAuth 2.0 和 OpenIdConnect ...
- openapi_MicroProfile OpenAPI上的Swagger UI
openapi MicroProfile OpenApi为我们提供了一种使用OpenApi 3描述我们JAX-RS API的标准化方法.如果您以前使用过swagger-jaxrs和swagger- 批 ...
- MicroProfile OpenAPI上的Swagger UI
MicroProfile OpenApi为我们提供了一种使用OpenApi 3描述我们JAX-RS API的标准化方法.如果您以前使用过swagger-jaxrs和swagger-annotation ...
- Spring Boot和Swagger UI
我已经一年没有从头开始开发Spring Web应用程序了,如果我不参加QA自动化工程师的培训,那么这段时间甚至会更长. 由于这个原因,我开发了一个示例REST应用程序. 除了Swagger,一切对我来 ...
- 使用Swagger UI的Document和Test API
目录 介绍 配置 可视化 测试 支持属性 支持XML文档 资源/材料/参考资料 介绍 开发人员通常通过浏览器请求或使用POSTMAN, Advanced Rest Client(ARC)等客户端来测 ...
最新文章
- 读博士所面临问题的解决对策
- 简单的使用Seajs
- django F和Q 关键字使用
- PostgreSQL 11 1Kw TPCC , 1亿 TPCB 7*24 强压耐久测试
- LeetCode 2023. 连接后等于目标字符串的字符串对
- visual studio如何中止正在运行的程序
- vue的transition组件的使用
- 据说有99%的人都会做错的面试题
- 拉普拉斯变换_拉普拉斯变换——奇妙的数学
- ABS 1.1.0:更多Python和Bash提供最有趣的编程语言
- sql domain credentail
- python数据驱动读取用例_利用Python如何实现数据驱动的接口自动化测试
- 怎样快速的学习微信小程序
- 简易留言板HTML+JS代码
- pajek的net文件格式
- 常见ERP软件简单介绍与个人评价
- 会员系统+企业微信+小程序,助力私域高效转化
- 什么是服务器、云服务的优缺点是什么、为什么要使用云服务器?
- git 删除历史commit
- PMP之项目采购管理