SpringBoot集成Swagger2自动生成友好的RestApi测试页面及文档
springBoot集成swagger2
水煮鱼又失败了
https://www.jianshu.com/p/002ce2f26103
1 背景
springBoot作为微服务首选框架,为其他服务提供大量的接口服务。接口对接方需要实时最近的接口文档。
swagger可以通过代码和注释
自动为web项目生成在线文档,这里使用swagger。
swagger官网地址:https://swagger.io/
2 使用
2.1 maven依赖
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version>
</dependency>
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version>
</dependency>
依赖说明:
(1)springfox-swagger2
检测spring的web请求信息,生成检测结果(json格式
)。
(2)springfox-swagger-ui
根据springfox-swagger2生成的数据,生成可视化
的友好页面。
2.2 配置代码
Springfox提供Docket对象,为其设置相关属性,将其注册成为spring的bean后,可以在接口文档中展示(可配置多个Docket的bean
,对应不同分组的接口)
@Configuration
@EnableSwagger2
public class Swagger2Conf {@Beanpublic Docket getUserDocket(){ApiInfo apiInfo=new ApiInfoBuilder().title("用户管理")//api标题.description("用户管理相关接口描述")//api描述.version("1.0.0")//版本号.contact("sabre")//本API负责人的联系信息.build();return new Docket(DocumentationType.SWAGGER_2)//文档类型(swagger2).apiInfo(apiInfo)//设置包含在json ResourceListing响应中的api元信息.select()//启动用于api选择的构建器.apis(RequestHandlerSelectors.basePackage("com.scaf.test.web.boot.controller.api"))//扫描接口的包.paths(PathSelectors.any())//路径过滤器(扫描所有路径).build();}
}
或者可以这样写:(https://www.jianshu.com/p/cbb6d89b88d8 差别各位细品)
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableSwagger2
public class Swagger2Config {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.gm.ds.api")).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("Simple APIs").description("simple apis").termsOfServiceUrl("http://www.gm.com").contact(new Contact("suliyea", "http://xxx", "suliyea@qq.com")).version("1.0").build();}}
其中@Configuration、@Bean均为spring初始化bean相关的注解。@EnableSwagger2
表示启用swagger2。
2.3 接口配置
通过在控制器和接口方法上加上相关注解
,可以给接口和控制器添加相关的接口说明
信息。
常用注解如下:
注解 | 使用的地方 | 用途 |
---|---|---|
@Api | 类/接口 | 描述类/接口主要用途 |
@ApiOperation | 方法 | 描述方法的用途 |
@ApiImplicitParam | 方法 | 用于描述接口的非对象参数 |
@ApiImplicitParams | 方法 | 用于描述接口的非对象参数集 |
@ApiIgnore | 类/方法/参数 | Swagger 文档不会显示拥有该注解的接口 |
@ApiModel | 参数实体类 | 可设置接口相关实体的描述 |
ApiModelProperty | 参数实体类属性 | 可设置实体属性的相关描述 |
参数实体类代码:
@ApiModel("用户")
public class UserInfo {@ApiModelProperty("用户ID")private Integer id;@ApiModelProperty("用户代码")private String userCode;@ApiModelProperty("用户姓名")private String userName;@ApiModelProperty("年龄")private Integer age;
}
接口代码:
@Api("用户管理api")
@RestController
@RequestMapping("/userApi")
public class UserApiController {@Autowiredprivate UserApiService userApiService;@ApiOperation("查询用户信息")@PostMapping("/findUserList")public JSONObject findUserList(){JSONObject jsonObject=new JSONObject();jsonObject.put("success",true);jsonObject.put("result",userApiService.findUserList());return jsonObject;}@ApiOperation("保存用户")@PostMapping("saveUser")public JSONObject saveUser(@RequestBody UserInfo userInfo){userApiService.saveUser(userInfo);JSONObject jsonObject=new JSONObject();jsonObject.put("success",true);jsonObject.put("message",null);return jsonObject;}
}
2.4 访问
启动项目后,通过以下方式访问swagger2的接口说明
http://地址:端口/应用名/swagger-ui.html
如:http://localhost:8080/swagger-ui.html
3 其他
3.1 访问swagger2接口源信息
通过如下方式访问:
http://地址:端口/应用名/v2/api-docs
如:http://localhost:8080/v2/api-docs
返回的json格式如下:
{"swagger":"2.0","info":{"description":"用户管理相关接口描述","title":"用户管理"},"host":"localhost:8080","basePath":"/","tags":[{"name":"user-api-controller","description":"User Api Controller"}],"paths":{"/userApi/findUserList":{"post":{"tags":["user-api-controller"],"summary":"findUserList","operationId":"findUserListUsingPOST","consumes":["application/json"],"produces":["*/*"],"parameters":[{"in":"body","name":"userInfo","description":"userInfo","required":true,"schema":{"$ref":"#/definitions/UserInfo"}}],"responses":{"200":{"description":"OK","schema":{"type":"object","additionalProperties":{"type":"object"}}},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}},"deprecated":false}},"/userApi/saveUser":{"post":{"tags":["user-api-controller"],"summary":"saveUser","operationId":"saveUserUsingPOST","consumes":["application/json"],"produces":["*/*"],"parameters":[{"in":"body","name":"userInfo","description":"userInfo","required":true,"schema":{"$ref":"#/definitions/UserInfo"}}],"responses":{"200":{"description":"OK","schema":{"type":"object","additionalProperties":{"type":"object"}}},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}},"deprecated":false}}},"definitions":{"UserInfo":{"type":"object","properties":{"age":{"type":"integer","format":"int32"},"id":{"type":"integer","format":"int32"},"userCode":{"type":"string"},"userName":{"type":"string"}},"title":"UserInfo"}}}
swagger-ui通过对此源信息的解析,生成相关页面
3.2 swagger2静态资源
swagger通过webjars的方式,来实现网页方式的接口访问。
如配置拦截器、shiro、spring security等,需对以下页面放行,来保证swagger页面的正常访问:
/swagger*/**
/v2/**
/webjars/**
如下,spring拦截器,需配置如下:
<mvc:exclude-mapping path="/swagger*/**"/>
<mvc:exclude-mapping path="/v2/**"/>
<mvc:exclude-mapping path="/webjars/**"/>
SpringBoot集成Swagger2自动生成友好的RestApi测试页面及文档相关推荐
- springboot 集成 swagger 自动生成API文档
Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的Web服务.简单来说,Swagger是一个功能强大的接口管理工具,并且提供了多种编程语言的前后端分离解决方案. S ...
- SpringBoot 集成Swagger2 | 快速生成开发文档 | 敏捷开发
使用 Swagger 开源和专业工具集简化用户.团队和企业的 API 开发. 一.Swagger是什么? 好处 实现更快.标准化的 API 设计 通过协作更智能地工作 托管的交互式 API 文档 二. ...
- 13.9 SpringBoot集成Swagger2中遇到的问题
13.9 SpringBoot集成Swagger2中遇到的问题 我们在使用SpringBoot集成Swagger2中,访问:http://127.0.0.1:8188/swagger-ui.html ...
- springboot集成swagger2,构建优雅的Restful API
springboot集成swagger2,构建优雅的Restful API 转载请标明出处: 原文首发于:https://www.fangzhipeng.com/springboot/2017/07/ ...
- 【快速上手系列】使用Springboot集成Swagger2的简单使用测试
[快速上手系列]使用Springboot集成Swagger2的简单使用测试 简介 Swagger2是为了解决企业中接口(api)中定义统一标准规范的文档生成工具. 尤其是前后端分离时对一些业务接口也不 ...
- SpringBoot集成Swagger2与Swagger3的区别
SpringBoot集成Swagger2与Swagger3的区别 前言 一.pom文件中引入Swagger依赖 Swagger2 Swagger3 二.Swagger配置 Swagger2 Swagg ...
- springboot集成swagger2测试接口
springboot集成swagger2测试接口 1.需要的依赖 2.开始编写一个swagger2 3.演示效果图片 1.需要的依赖 <dependency><groupId> ...
- springboot集成swagger2多模块中文配置详细步骤,解决集成mybatis或mybatis-plus无法正常使用问题
springboot集成swagger2多模块中文配置详细步骤,解决集成mybatis或mybatis-plus无法正常使用问题 参考文章: (1)springboot集成swagger2多模块中文配 ...
- springboot集成swagger2构建RESTful API文档
在开发过程中,有时候我们需要不停的测试接口,自测,或者交由测试测试接口,我们需要构建一个文档,都是单独写,太麻烦了,现在使用springboot集成swagger2来构建RESTful API文档,可 ...
最新文章
- RabbitMQ 入门系列(9)— Python 的 pika 库常用函数及参数说明
- php 压测流量回放,终极 Web 应用性能和压力测试工具 Gor
- 机器学习(MACHINE LEARNING) 【周志华版-”西瓜书“-笔记】 DAY14-概率图模型
- 进阶学习(3.10) Adapter Pattern 适配器模式
- 在.NET中使用iTextSharp创建/读取PDF报告: Part I [翻译]
- Spring MVC-08循序渐进之国际化(基于Session-SessionLocaleResolver)
- Properties的使用
- ListDataView:让你的List可以被任何Site引用
- python面试题37道(附答案)看完面试不愁了
- 《现代前端技术解析》第七章读书笔记
- 教你给视频添加马赛克的剪辑技巧,轻松简单
- 给学校开放计算机建议书30字,学生给学校建议书
- 一个农村孩子的大城市梦想之深入江湖!
- promise跟ajax区别,Promise和AJAX有什么区别?
- 电脑一会,电脑一会黑屏一会正常怎么回事
- 领域驱动(DDD)设计
- 同期及上期数据对比显示
- 虚拟机Linux的安装
- 计算机网络——3A安全认证
- 【KCTF2020秋季赛】异常信号 WriteUp
热门文章
- Arduino采集Microzone遥控器信号(ROSMicrozoneBridge)
- 力扣——删除有序数组中的重复项
- JBDC操作事务源码解析
- [翻译]Hystrix wiki–How it Works
- 给你一个全自动的屏幕适配方案(基于SW方案)二 —— Calces.Screen插件拓展功能升级...
- luaL_dofile和luaL_loadfile的区别
- 201612-1-中间数
- 在Unity中实现屏幕空间反射Screen Space Reflection(2)
- java pdf在线阅读插件_JAVA实现在线查看PDF和office文档
- .国内外主流前端开发框架对比