Spring Boot成长之路 03 - 使用swagger构建你的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还提供一些可扩展插件，并支持自定义插件，有兴趣的可以查看官方文档研究研究。