前言
Spring Boot框架是目前十分风行的微服务框架，咱们很多状况下应用它来提供 Rest API。而对于 Rest API 来说很重要的一部分内容就是文档，Swagger 为咱们提供了一套通过代码和注解主动生成文档的办法，这一点对于保障 API 文档的及时性将有很大的帮忙。本文将应用 Swagger 2 标准的 Springfox 实现来理解如何在Spring Boot 我的项目中应用 Swagger，次要蕴含了如何应用Swagger 主动生成文档、应用 Swagger 文档以及 Swagger 相干的一些高级配置和注解。
Swagger 简介
Swagger是一套基于 OpenAPI 标准构建的开源工具，能够帮忙咱们设计、构建、记录以及应用Rest API。Swagger 次要蕴含了以下三个局部：
Swagger Editor：基于浏览器的编辑器，咱们能够应用它编写咱们 OpenAPI 标准。Swagger UI：它会将咱们编写的 OpenAPI 标准出现为交互式的 API 文档，后文我将应用浏览器来查看并且操作咱们的 Rest API。Swagger Codegen：它能够通过为 OpenAPI（以前称为 Swagger）标准定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。
为什么要应用 Swagger
当下很多公司都采取
前后端拆散的开发模式，前端和后端的工作由不同的工程师实现。在这种开发模式下，维持一份及时更新且残缺的 Rest API 文档将会极大的进步咱们的工作效率。传统意义上的文档都是后端开发人员手动编写的，置信大家也都晓得这种形式很难保障文档的及时性，这种文档长此以往也就会失去其参考意义，反而还会加大咱们的沟通老本。而 Swagger 给咱们提供了一个全新的保护 API 文档的形式，上面咱们就来理解一下它的长处：
代码变，文档变。只须要大量的注解，Swagger 就能够依据代码主动生成 API 文档，很好的保障了文档的时效性。跨语言性，反对 40 多种语言。Swagger UI出现进去的是一份可交互式的 API 文档，咱们能够间接在文档页面尝试 API 的调用，省去了筹备简单的调用参数的过程。- 还能够将文档标准导入相干的工具（例如
SoapUI）, 这些工具将会为咱们主动地创立自动化测试。以上这些长处足以阐明咱们为什么要应用
Swagger了，您是否曾经对 Swagger 产生了浓重的趣味了呢？上面咱们就将一步一步地在Spring Boot 我的项目中集成和应用 Swagger，让咱们从筹备一个 Spring Boot 的 Web 我的项目开始吧。
SpringBoot整合Swagger2
SpringBoot整合Swagger2-后期筹备
- 首先创立一个根底的
SpringBoot web我的项目。您能够通过Spring Initializr页面生成一个空的 Spring Boot 我的项目，或者通过idea创立一个SpringBoot我的项目 -
增加依赖
-
-
Spring Boot的Web依赖<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> -
集成swagger2<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency>
-
-
集成Swagger UI<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
SpringBoot整合Swagger2-外围在这里插入代码片代码编写
java中Swagger2配置-间接上配置代码，Swagger2的配置是比拟容易的，在胜利我的项目创立之后，只须要开发者本人提供一个Docket的Bean.（正文写的很分明，这里就不一一解释了。不懂的中央能够在片尾关注我公众号加我WX。）
/**
* 集成swagger2 解决前后端拆散 弊病：不能及时协商+尽早解决的问题
* 应用swagger总结:
* 通过swagger 给一些比基奥难了解的接口或属性，减少正文信息
* 接口文档实时更新
* 能够在线测试
* 平安问题:
* 正式上线的时候 记得敞开swagger
*/
@Configuration//加载到springboot配置外面
@EnableSwagger2//开启swagger2
public class SwaggerConfig {
/**
* 配置swagger2
* 注册一个bean属性
* swagger2其实就是从新写一个结构器，因为他没有get set办法\
* enable() 是否启用swagger false swagger不能再浏览器中拜访
* groupName()配置api文档的分组 那就注册多个Docket实例 相当于多个分组
* @return
*/
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("qlh")//组名称
.enable(true)
.select()
/**
* RequestHandlerSelectors配置扫描接口的形式
* basePackage 配置要扫描的包
* any 扫描全副
* none 不扫描
* withClassAnnotation 扫描类上的注解
* withMethodAnnotation 扫描办法上的注解
*/
.apis(RequestHandlerSelectors.basePackage("com.tinygray.madison.controller"))
/**
* paths() 扫描过滤形式
* any过滤全副
* none不过滤
* regex正则过滤
* ant过滤指定门路
*/
// .paths(PathSelectors.ant("/login/**"))
.build();
}
/**
* 配置swagger2信息 =apiInfo
* @return
*/
public ApiInfo apiInfo(){
/*作者信息*/
// Contact contact = new Contact("XXX", "http://baidu.com", "email");
Contact contact = new Contact("", "", "");
return new ApiInfo(
"XXX的API接口",
"company接口",
"V1.0",
"urn:toVs",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}SpringBoot整合Swagger2-接口编写
- 编写一些简略的java接口。（你能够依据你的状况进行编写）
@Api(tags = "TestController测试")
@RestController
public class TestController {
@ApiOperation("login api")
@GetMapping("/")
public String login() {
return "Hello login ~";
}
@ApiOperation("helloWord Api")
@GetMapping("/index")
public String index() {
return "Hello World ~";
}
@ApiOperation("admin Api")
@GetMapping("/admin/hello")
public String admin() {
return "hello admin!";
}
@ApiOperation("user Api")
@GetMapping("/user/hello")
public String user() {
return "hello user";
}
}SpringBoot整合Swagger2-胜利展现
- 验证代码-到这里咱们曾经胜利集成Swagger2，而后启动我的项目，输出http://localhost:8080/swagger-ui.html，如果能呈现上面界面，阐明配置胜利了。
- 未完待续。下章节解说Swagger的罕用注解
(SpringBoot中优雅的应用Swagger2【史上最全注解篇】-【2/2】)。
结束语
感激浏览小生文章。祝大家
早日富可敌国，实现财产自在。记得
点赞、评论、珍藏哦。有任何问题能够在微信搜寻
公众号：Madison龙少进行征询或者微信扫描上面二维码进行征询
发表回复