Spring Boot整合Swagger教程

Swagger

介绍

• Swagger是一款REST APIs文档生成工具。
• Swagger官方定义：Swagger是一款开源工具，依据OpenAPI规范（OpenAPI Specification，简称OAS）可以帮助你设计，构建，生成文档，消费（调用）REST APIs。主要的工具包含：
• Swagger Editor：基于web的一个工具，用于编写符合OpenAPI规范的模型
• Swagger UI：用于展示REST APIs文档，并提供一些交互操作
• Swagger Codegen： 依据OpenAPI规范来生成服务端和客户端代码

优点

• 通过代码和注释自动生成文档。在Swagger框架下，开发人员可对服务进行归类说明，对方法，模型，返回结果等进行详细说明。方便开发人员在编写代码的同时，编写文档信息。自动生成，只需很少的编辑工作，就能获得完整的REST APIs文档
• 提供了UI界面。既展示接口信息，又提供了参数校验，测试功能
• 形成了文档规范，支持不同的语言
• 提供丰富的组件。

SpringBoot+Swagger集成

使用官方依赖

• 在pom.xml文件中添加Swagger相关依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<!-- API获取的包 -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<!-- 官方给出的一个ui界面，这个界面可以自定义，默认是官方的 -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/org.codehaus.jackson/jackson-core-asl -->
<!-- 测试数据以JSON格式返回的依赖包 -->
<dependency>
	<groupId>org.codehaus.jackson</groupId>
	<artifactId>jackson-core-asl</artifactId>
	<version>1.9.13</version>
</dependency>```

配置Swagger

• 要使用Swagger，我们必须对Swagger进行配置，我们需要创建一个Swagger的配置类，比如可以命名为SwaggerConfig.java

package com.dduan.common;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration //标明是配置类
@EnableSwagger2 //开启swagger功能
public class SwaggerConfig implements WebMvcConfigurer {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)  //DocumentationType.SWAGGER_2 固定的，代表swagger2
                //.groupName("分布式任务系统") //如果配置多个文档的时候，那么需要配置groupName来分组标识
                .apiInfo(apiInfo()) //用于生成API信息
                .select() //select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
                .apis(RequestHandlerSelectors.basePackage("com.dduan.controller")) //用于指定扫描哪个包下的接口
                .paths(PathSelectors.regex(".sys/login"))//选择所有的API,如果你想只为部分API生成文档，可以配置这里
                .build();
    }

    /**
     * 用于定义API主界面的信息，比如可以声明所有的API的总标题、描述、版本
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XX项目API") //可以用来自定义API的主标题
                .description("XX项目SwaggerAPI管理") //可以用来描述整体的API
                .termsOfServiceUrl("") //用于定义服务的域名
                .version("1.0") //可以用来定义版本。
                .build();
    }

    /**
     * swagger-ui.html访问不了，页面报错404,解决办法
     *
     * @param registry 注意：重写 addResourceHandlers 方法需要 implements WebMvcConfigurer 类
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {

        registry
                .addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry
                .addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

场景

• @Api 定义接口组

@Api(tags = "用户管理")
@RestController
@RequestMapping("/sys")
public class UserController {
}

• @ApiOperation 定义接口

@Api(tags = "用户管理")
@RestController
@RequestMapping("/sys")
public class UserController {
	@ApiOperation(value = "用户登录")
    @RequestMapping(value = "/login", method = RequestMethod.POST, consumes = MediaType.APPLICATION_JSON_VALUE)
    public Resp login(@RequestBody LoginVo loginVo) {
    }
}

接口文档展示

• 访问地址：localhost:端口号/swagger-ui.html
• API doc 页面及功能介绍
  
• 点击 Try it out 按钮页面