SpringBoot集成Springfox 3.0使用Swagger2.0生成

SpringBoot集成Springfox 3.0

Springfox介绍

Swagger

Swagger是一套用于RESTful API开发的工具，可以生成非常直观的接口文档用于前后端分离的接口交流。

Springfox

SpringFox是一个扫描代码中的信息，生成API文档的工具。API文档的格式不止swagger的OpenAPI规范，还有RAML、jsonAPI等。

Springfox官方文档

使用Springfox

Maven

引入最新版的Springfox依赖

	<repositories>
		<repository>
			<id>jcenter-snapshotsid>
			<name>jcentername>
			<url>https://jcenter.bintray.com/url>
		repository>
	repositories>
	<dependencies>
		<dependency>
			<groupId>io.springfoxgroupId>
			<artifactId>springfox-boot-starterartifactId>
			<version>3.0.0version>
		dependency>
	dependencies>

SwaggerConfig

新建Swagger配置文件 SwaggerConfig（命名没有要求）

package com.usongon.starfire.bean.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @author usongon
 * @date 2020/10/23
 */
@Configuration
@EnableWebMvc
public class SwaggerConfig extends WebMvcConfigurationSupport {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .select()
                //"com.usongon.starfire" 是扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.usongon.starfire"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo getApiInfo(){
        return new ApiInfoBuilder()
                //项目标题
                .title("星火") 
                //项目描述
                .description("星火项目接口文档")
                //版本
                .version("1.0.0")
                //联系方式
                .contact(new Contact("usongon", "usongon.com", "[email protected]"))
                .build();
    }
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        //解决跨域问题
        registry.addResourceHandler("/**").addResourceLocations("/");
    }
}

在Controller中测试

在Controller文件中使用注解，示例代码如下：

package com.usongon.starfire.controller;

import com.usongon.starfire.service.IUserInfoService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.annotation.Resource;

/**
 * @author usongon
 * @date 2020/10/23
 */
@Api(value = "用户模块")
@RestController
@RequestMapping("/user")
public class UserInfoController {
    @Resource
    private IUserInfoService userInfoService;

    @ApiOperation(value = "获取全部用户信息", notes = "暂时无须参数")
    @PostMapping("/getAll")
    public String getAllUserInfo(){
        return userInfoService.list().toString();
    }
}

常用Swagger注解如下：

@Api：修饰整个类，描述Controller的作用 
@ApiOperation：描述一个类的一个方法，或者说一个接口 
@ApiParam：单个参数描述 
@ApiModel：用对象来接收参数 
@ApiModelProperty：用对象接收参数时，描述对象的一个字段 
@ApiResponse：HTTP响应其中1个描述 
@ApiResponses：HTTP响应整体描述 
@ApiIgnore：使用 该注解忽略这个API 
@ApiError ：发生错误返回的信息 
@ApiImplicitParam：一个请求参数 
@ApiImplicitParams：多个请求参数 
@ApiImplicitParam属性：
	paramType 查询参数类型 
		path 以地址的形式提交数据 
		query 直接跟参数完成自动映射赋值 
		body 以流的形式提交 仅支持POST 
		header 参数在request headers 里边提交 
		form 以form表单的形式提交 仅支持POST 
	dataType 参数的数据类型 只作为标志说明，并没有实际验证 Long String 
	name 接收参数名 
	value 接收参数的意义描述 
	required 参数是否必填 true 必填 false 非必填 
	defaultValue 默认值 

运行项目，访问http://host/context-path/swagger-ui/index.html 或者 http://host/context-path/swagger-ui/

如 localhost:8080/swagger-ui/index.html

注意，在Springfox3.0之前，访问地址为http://host/context-path/swagger-ui.html

如 localhost:8080/swagger-ui.html

在升级为Springfox3.0之后，访问地址发生了变化，这一点要注意。

在这里我们就能看见我们编写的api文档了，点击user-info-controller(根据controller文件的名字自动生成的)，我们可以看见接口信息

我们可以点击之后看见详情

并可以点击 try it out来进行测试

导入接口信息到Postman

在项目名下方有一个地址

复制这个地址，打开Postman，点击import

点击link，粘贴我们刚才复制的地址

点击Continue，再点击import就可以导入了，这时我们就可以在Collections中看到我们导入的接口信息了！

Springfox2.x迁移至Springfox3.0

1. 在maven配置文件pom.xml中删除 springfox-swagger2和springfox-swagger-ui 依赖
2. 在配置文件中删除@EnableSwagger2注释
3. 添加 springfox-boot-starter (参考上方教程第一步)
4. 如果使用的是WebMvc，但尚未使用@EnableWebMvc注释，请添加此注释。

参考文档

Springfox官方文档