SpringBoot中优雅的使用Swagger2

前言

　　Spring Boot 框架是目前很是流行的微服务框架，咱们不少状况下使用它来提供 Rest API。而对于 Rest API 来讲很重要的一部份内容就是文档，Swagger 为咱们提供了一套经过代码和注解自动生成文档的方法，这一点对于保证 API 文档的及时性将有很大的帮助。本文将使用 Swagger 2 规范的 Springfox 实现来了解如何在 Spring Boot 项目中使用 Swagger，主要包含了如何使用 Swagger 自动生成文档、使用 Swagger 文档以及 Swagger 相关的一些高级配置和注解。

Swagger 简介

Swagger 是一套基于 OpenAPI 规范构建的开源工具，能够帮助咱们设计、构建、记录以及使用 Rest API。Swagger 主要包含了如下三个部分：

1. Swagger Editor：基于浏览器的编辑器，咱们可使用它编写咱们 OpenAPI 规范。

2. Swagger UI：它会将咱们编写的 OpenAPI 规范呈现为交互式的 API 文档，后文我将使用浏览器来查看而且操做咱们的 Rest API。

3. Swagger Codegen：它能够经过为 OpenAPI（之前称为 Swagger）规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。

为何要使用 Swagger

当下不少公司都采起先后端分离的开发模式，前端和后端的工做由不一样的工程师完成。在这种开发模式下，维持一份及时更新且完整的 Rest API 文档将会极大的提升咱们的工做效率。传统意义上的文档都是后端开发人员手动编写的，相信你们也都知道这种方式很难保证文档的及时性，这种文档长此以往也就会失去其参考意义，反而还会加大咱们的沟通成本。而 Swagger 给咱们提供了一个全新的维护 API 文档的方式，下面咱们就来了解一下它的优势：

1. 代码变，文档变。只须要少许的注解，Swagger 就能够根据代码自动生成 API 文档，很好的保证了文档的时效性。

2. 跨语言性，支持 40 多种语言。

3. Swagger UI 呈现出来的是一份可交互式的 API 文档，咱们能够直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。

4. 还能够将文档规范导入相关的工具（例如 SoapUI）, 这些工具将会为咱们自动地建立自动化测试。

以上这些优势足以说明咱们为何要使用 Swagger 了，您是否已经对 Swagger 产生了浓厚的兴趣了呢？下面咱们就将一步一步地在 Spring Boot 项目中集成和使用 Swagger，让咱们从准备一个 Spring Boot 的 Web 项目开始吧。

SpringBoot整合Swagger2

1. 首先建立一个基础的SpringBoot web项目。您能够经过 Spring Initializr 页面生成一个空的 Spring Boot 项目，或者经过idea建立一个SpringBoot项目

2. 添加依赖

   1. Spring Boot 的 Web 依赖　

      <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
      </dependency>

   2. 集成swagger2　

      <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
      </dependency>

   3. 集成Swagger UI

      <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
      </dependency>

3. 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("XXX")//组名称
                   .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());
       }
   ​
   }

    

4. 编写一些简单的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";
       }
   }

5. 验证代码-到这里咱们已经成功集成Swagger2，而后启动项目，输入http://localhost:8080/swagger-ui.html，若是能出现下面界面，说明配置成功了。
6. 未完待续。下章节讲解Swagger的经常使用注解。

   这篇文章是否帮助到你呢？扫描关注公众号--【Madison龙少】，【Madison龙少】公众号天天提供java干货，干货满满。