SpringBoot集成swagger

Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。
官网地址：swagger.io

SpringBoot集成swagger

swagger有swagger2和swagger3两个版本，两个版本引入的依赖不同，展示的UI界面也不同，本文以swagger2为例。

引入swagger依赖


    io.springfox
    springfox-swagger2
    2.9.2


    io.springfox
    springfox-swagger-ui
    2.9.2

新建config类
新建一个swagger的配置类，在该类上使用注解@EnableSwagger2即可开启swagger，此注解也可放在服务启动类上；

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.
                basePackage("com.test.manager.controller")).paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("Manage Swagger").description("管理系统OpenAPI").version("1.0").build();
    }
}

添加API接口说明
swagger api所使用到的注解及其作用如下所示。

注解	使用位置	作用
@Api(tags = {“用户接口”})	controller类	接口分组说明
@ApiOperation(“更新用户启停状态”)	请求接口方法	方法作用说明
@ApiParam(“用户ID”)	针对方法的单个参数	参数说明
@ApiModel	针对方法的实体参数，在实体类上增加此注解	实体说明
@ApiModelProperty(“主键ID”)	实体类的属性	属性字段作用说明

UI优化
swagger默认的UI不太符合大家的使用习惯，网上有一个优化swagger UI的开源项目，优化后的页面与postman类似。此项目GitHub开源地址：swagger-bootstrap-ui
只需要引入一个依赖即可优化界面：


    com.github.xiaoymin
    swagger-bootstrap-ui
    1.9.6

或者引入新版本的knife4j：


    com.github.xiaoymin
    knife4j-spring-boot-starter
    ${knife4j.version}

优化前swagger访问地址：http://ip:port/swagger-ui.html#/
优化后swagger访问地址：http://ip:port/doc.html#/

部署不同环境如何关闭swagger
针对prod生产环境如何关闭swagger api访问呢？

方法一：可以使用注解@Profile判断配置文件，如果不是prod则启用，否则默认启用swagger，代码如下。

@Configuration
@EnableSwagger2
@Profile("!prod")
public class Swagger2Config {
    ...
}

方法二：在config类配置注解@ConditionalOnProperty

@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")

在prod yaml配置文件中增加swagger开关，当值为true时为开启。

swagger：
  enable: false

SpringBoot集成swagger

Java相关栏目本月热门文章