SpringBoot集成Swagger（Springfox）自动生成API文档

版权声明：本文为博主原创文章，未经博主允许不得转载。 https://blog.csdn.net/weixin_37490221/article/details/86144452

也许，你事先需要了解Swagger和Springfox的关系，然后我默认大家都在使用SpringBoot，并且对Java和Spring有一定的开发基础。

万物皆麻烦，直接上代码（博文末尾有github源码地址）

1.pom文件

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>

	<!-- 2.0.3版本的spring-boot-starter-parent -->
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.0.3.RELEASE</version>
		<relativePath/>
	</parent>

	<!-- 项目相关 -->
	<groupId>com.zaomianbao</groupId>
	<artifactId>swagger</artifactId>
	<version>1.0.0</version>
	<name>swagger</name>
	<description>Demo project for Swagger</description>

	<!-- java版本 -->
	<properties>
		<java.version>1.8</java.version>
	</properties>

	<dependencies>

		<!-- SpringBoot相关依赖 -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-devtools</artifactId>
			<scope>runtime</scope>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>

		<!-- lombok敏捷开发工具包-->
		<dependency>
			<groupId>org.projectlombok</groupId>
			<artifactId>lombok</artifactId>
			<optional>true</optional>
		</dependency>

		<!-- google guava util-->
		<dependency>
			<groupId>com.google.guava</groupId>
			<artifactId>guava</artifactId>
			<version>27.0.1-jre</version>
		</dependency>

		<!-- springfox -->
		<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>

		<!-- json -->
		<dependency>
			<groupId>com.fasterxml.jackson.core</groupId>
			<artifactId>jackson-databind</artifactId>
			<version>2.6.5</version>
		</dependency>
		<dependency>
			<groupId>com.fasterxml.jackson.core</groupId>
			<artifactId>jackson-databind</artifactId>
			<version>2.9.6</version>
		</dependency>
		<dependency>
			<groupId>com.fasterxml.jackson.core</groupId>
			<artifactId>jackson-annotations</artifactId>
			<version>2.9.0</version>
		</dependency>
		<dependency>
			<groupId>com.google.code.gson</groupId>
			<artifactId>gson</artifactId>
			<version>2.7</version>
		</dependency>
		<dependency>
			<groupId>com.alibaba</groupId>
			<artifactId>fastjson</artifactId>
			<version>1.2.47</version>
		</dependency>
	</dependencies>

	<!-- SpringBoot的maven插件 -->
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

这里面最重要的是springfox的两个配置

<!-- swagger核心组件，在代码配置swagger时会依赖到它 -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>
<!-- swagger的用户界面，用于展示api接口文档 -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.2</version>
</dependency>

2.Swagger配置类

package com.zaomianbao.swagger.config;

import com.google.common.base.Predicate;
import com.zaomianbao.swagger.annotation.SwaggerCustomIgnore;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;
import static com.google.common.base.Predicates.*;
import static springfox.documentation.builders.RequestHandlerSelectors.*;
import static springfox.documentation.builders.PathSelectors.*;

/**
 * @Description Swagger配置文件
 * @Author zaomianbao
 * @Date 2019/1/9
 **/
//该类依赖了google的guava组件和springfox.documentation组件
@Configuration
@EnableSwagger2
//包扫描，在此包下的Controler都会被纳入swagger接口文档生成的范围，这里也可以配置类扫描，同时也可以在这个配置类里面细化过滤规则
@ComponentScan(basePackages = "com.zaomianbao.swagger.controller")
public class SpringfoxSwagger2Config {

    //组织Docket对象，翻译过来就是摘要的意思，它是生成API文档的核心对象，里面配置一些必要的信息
    @Bean
    public Docket swaggerSpringMvcPlugin(){
                        //指定规范，这里是SWAGGER_2
        return new Docket(DocumentationType.SWAGGER_2)
                //设定Api文档头信息，这个信息会展示在文档UI的头部位置
                .apiInfo(swaggerDemoApiInfo())
                .select()
                //添加过滤条件，谓词过滤predicate，这里是自定义注解进行过滤
                .apis(not(withMethodAnnotation(SwaggerCustomIgnore.class)))
                //这里配合@ComponentScan一起使用，又再次细化了匹配规则(当然，我们也可以只选择@ComponentScan、paths()方法当中的一中)
                .paths(allowPaths())
                .build();
    }

    /**
     * 自定义API文档基本信息实体
     * @return
     */
    private ApiInfo swaggerDemoApiInfo(){
        //构建联系实体，在UI界面会显示
        Contact contact = new Contact("枣面包", "http://www.zaomianbao.com", "[email protected]");
        return new ApiInfoBuilder()
                    .contact(contact)
                    //文档标题
                    .title("Swagger2构建RESTful API文档")
                    //文档描述
                    .description("SpringBoot集成Springbox开源项目，实现OAS，构建成RESTful API文档")
                    //文档版本
                    .version("1.0.0")
                    .build();
    }

    /**
     * path匹配规则
     * @return
     */
    private Predicate<String> allowPaths(){
        return or(
                regex("/user.*"),
                regex("/role.*")
        );
    }
}

配置是自定义的，有些配置可以没有，有些配置可以再加上，多余配置可以参考官方文档：Springfox Reference Documentation

3.忽略接口注解SwaggerCustomIgnore

这个注解在Swagger配置类中和下面的范例UserController中使用到了，哪个方法被该注解标注了，那么对应方法的接口就会被API文档忽略构建

package com.zaomianbao.swagger.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * 忽略接口注解
 */
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface SwaggerCustomIgnore {
}

4.范例UserController

这里提供了一些范例接口，供生成API文档

package com.zaomianbao.swagger.controller;

import com.zaomianbao.swagger.annotation.SwaggerCustomIgnore;
import com.zaomianbao.swagger.entity.User;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.Arrays;

/**
 * @Description 用户控制层
 * @Author zaomianbao
 * @Date 2019/1/9
 **/
@RestController
@RequestMapping("/user")
public class UserController {

    @SwaggerCustomIgnore
    @GetMapping("/list")
    public Object getUserList(){
        return Arrays.asList(User.builder().age(18).username("枣面包").build());
    }

    @PostMapping("create")
    public Object creteUser(){
        return User.builder().age(18).username("枣面包").build();
    }
}

5.使用到的实体User

使用到的实体，这里使用的lombok组件，在pom中已经引入

package com.zaomianbao.swagger.entity;

import lombok.Builder;
import lombok.Data;

/**
 * @Description 用户实体
 * @Author zaomianbao
 * @Date 2019/1/9
 **/
@Data
@Builder
public class User {

    private String username;
    private Integer age;
}

6.项目包结构

7.Swagger-UI

启动项目直接访问：http://localhost:8080/swagger-ui.html

UI和配置的对应关系

1.对应配置里的title
2.对应配置里的version
3.对应配置里的description
4.对应配置里的Contact对象
5.对应配置里的@ComponentScan注解、paths()方法、allowPaths()方法、UserControler里@SwaggerCustomIgnore注解共同作用下展示出来的结果

在swagger-ui里我们还可以模拟请求，直接测试接口的功能

点击每个接口对应的显示区域 --> 点击"try it out" --> 点击"execute"即可

8.注意

在我们的接口所在的Controller里其实可以配置很多注解用于描述和丰富API文档，但是博主这里并没有使用，当然，没有配置那么多注解也一样可以使用，一样可以生成API文档，只是那些注解会丰富生成的JSON格式的API文档文件(这个可以在博主之前的博客中找到原因：Swagger和Springfox的关系)，然后通过swagger-ui展示给大家而已。这里只是一个入门，和扫盲的过程。

9.github源码地址

https://github.com/zaomianbao/swagger

10.总结

如有错误，请在留言板给博主留言，博主会第一时间更正。

参考：

https://swagger.io/
http://springfox.github.io/springfox/docs/snapshot/
http://www.cnblogs.com/getupmorning/p/7267076.html
http://springfox.github.io/springfox/
https://petstore.swagger.io/
https://editor.swagger.io/
https://www.jianshu.com/p/cdb41c9e52e2
https://github.com/swagger-api
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md