文章目录

• 简述
• Swagger
• SpringFox
• 联系
• 链接

• 入门
• 添加统一的swagger配置
• 常用注解
• 接口参数方式
• Model方式
• 过滤API

简述

Swagger

据官网介绍，swagger是最好的构建API工具，通过此工具可以构建良好标准的API接口，具备以下特点：

• 设计：根据规范的标准设计和建模API
• 构建：支持多种语言构建API
• 文档：提高开发人员使用交互式API文档的经验
• 测试：提供简单的功能测试
• 标准化：可设置和限制项目中所使用的API风格

SpringFox

SpringFox：支持在Spring环境中构建JSON API文档

联系

对于大多数刚接触swagger的人，可能经常搞混 swagger 与 springfox-swagger-ui，误以为我们在springboot中所使用的就是swagger了。但其实这样并不严谨，只能说swagger是一种规范，而我们在springboot项目中所使用的第三方包是对swagger的一种封装，使得我们可以在spring项目中可以轻松使用swagger编写API文档。

swagger 与 springfox-swagger-ui 之间的关系 ，在spring-fox官方使用文档中我们可以找到作者的一些答疑：

链接

swagger：https://swagger.io/
SpringFox：http://springfox.github.io/springfox/
Springfox使用文档：http://springfox.github.io/springfox/docs/snapshot/

使用

在此，将介绍如何在springboot项目中使用springfox-swagger-ui 搭建项目API文档，以及一些常用的API文档配置。

入门

1、pom.xml文件中引入springfox-swagger-ui 包

<properties>
<springfox.version>2.9.2</springfox.version>
</properties>

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${springfox.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${springfox.version}</version>
</dependency>

2、在springboot 启动器上添加@EnableSwagger2注解即可

@SpringBootApplication
@EnableSwagger2
public class SpringBootApplication {
}

3、启动项目，访问 http://XXXX/swagger-ui.html 即可

添加统一的swagger配置

此外，我们可以设置项目中统一的swagger配置，如：是否开启swagger文档，文档信息介绍，API扫描路径，过滤路径等等。

1、在application.yml 中添加配置
说明：

• 当项目发布时，可以将enable值改为false时，即不会将API文档暴露在外部环境中。
• path-mapping：一般用于项目真实访问路径与API文档请求路径不一致时，如在nginx的location中配置了路径映射/csdn，而通过带/csdn/xxxx/swagger-ui.html 访问API文档时，若无为swagger配置路径映射，则会导致请求接口地址错误。

# swagger 配置
swagger-config:
enable: true
path-mapping: /csdn

2、创建配置类SwaggerConfig.java
在此配置类添加@EnableSwagger2后，可不必在springboot的启动器上加入此注解。

@ConditionalOnProperty(name = "swagger-config.enable", matchIfMissing = false)
@Configuration
@ConfigurationProperties(prefix = "swagger-config")
@EnableSwagger2
public class SwaggerConfig {
private String pathMapping;

public String getPathMapping() {
return pathMapping;
}

public void setPathMapping(String pathMapping) {
this.pathMapping = pathMapping;
}

@Bean
public Docket demoApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(initDemoApiInfo())
.pathMapping(pathMapping)        // 文档路径映射，相当于web项目中的context-path
.select()  // 选择那些路径和api会生成document
.apis(RequestHandlerSelectors.any())    // 对所有api进行监控
.paths(PathSelectors.any())     // 扫描路径：对所有路径进行监控
.paths(Predicates.not(PathSelectors.regex("/error.*")))     // 过滤掉文档中显示的basic-error-controller
.build();
}

private ApiInfo initDemoApiInfo() {
// 文档标题，文档描述，文档版本，项目团队介绍地址，联系方式，许可证，许可证地址，供应商扩展集合
ApiInfo apiInfo = new ApiInfo(
"SpringBoot demo API title",
"this is description",
"1.0",
"https://blog.csdn.net/weixin_44374482",
new Contact("码诗人生", "https://blog.csdn.net/weixin_44374482", "@mail.com"),
"licence text",
"https://blog.csdn.net/weixin_44374482",
new ArrayList());

return apiInfo;
}

}

3、文档基本信息展示效果

常用注解

接口参数方式

@ApiOperation
@ApiImplicitParams、@ApiImplicitParam
@ApiParam

@PostMapping("/userLogin")
@ApiOperation(value = "用户登录", notes = "用户登录接口，通过手机号码和密码登录")
@ApiImplicitParams({
@ApiImplicitParam(name = "header1", value = "this is head1", defaultValue = "head1 value", paramType = "header"),
@ApiImplicitParam(name = "header2", value = "this is head2", paramType = "header")
})
public String userLogin(
@ApiParam(name = "phone", value = "手机号码", defaultValue = "123456", required = true) @RequestParam String phone,
@ApiParam(name = "password", value = "密码", required = true) @RequestParam String password) {

return "登录成功";
}

效果预览

Model方式

@ApiModelProperty

public class LoginUser {
@ApiModelProperty(name = "phone",
value = "手机号码",
required = true)
private String phone;

@ApiModelProperty(name = "password",
value = "密码",
required = true)
private String password;

... 省略get、set方法
}

@PostMapping("/userLoginByModel")
@ApiOperation(value = "用户登录", notes = "用户登录接口，通过手机号码和密码登录")
public String userLoginByModel(LoginUser user) {
System.out.println(user.getPhone());
return "登录成功";
}

效果预览

过滤API

默认情况下，swagger-fox 会扫描项目目录下的所有API。当项目中某个API不想暴露出来，但又不想在配置类中编写麻烦的过滤条件时，可以使用 @ApiIgnore 注解。
使用方法：

• 在controller头部添加，作用域为整个controller下的API
• 在单独某个接口方法上添加，作用域仅作用于该接口

此外，SpringFox还提供一些可扩展插件，并支持自定义插件，有兴趣的可以查看官方文档研究研究。