前言
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 龙少进行征询或者微信扫描上面二维码进行征询