Swagger简单配置

Swagger简单配置

基于springboot

springboot集成swagger

1. 导入相关依赖

<!--到入swagger的依赖（springboot 整合 swagger）-->
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<!--3.0版本之前-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>

2. 编写Swagger配置类

@Configuration 
@EnableSwagger2   // 开启swagger的自动配置
public class SwaggerConfig {
    // 配置swagger
    @Bean    // 加入到spring容器中
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2);
    }
}

3. 运行，访问 http://localhost:8080/swagger-ui/index.html（3.0的版本），如果是2的版本，访问 http://localhost:8080/swagger-ui.html

会出现如下问题：

• org.springframework.context.ApplicationContextException: Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException
• 访问 http://localhost:8080/swagger-ui/index.html 404

解决：

• 在主运行类上加上两个注解 @EnableWebMvc（解决问题一） @EnableOpenApi（解决问题二）

• 使用 @EnableOpenApi 注解还需要重新导入swagger3.0重新整合的依赖 springfox-boot-starter

  <!--集成了springfox-swagger-ui   springfox-swagger2-->
  <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-boot-starter</artifactId>
      <version>3.0.0</version>
  </dependency>
  

• 删除之前导入的两个依赖

配置swagger

自定义ApiInfo

// 配置文档信息， 源码只有构造器
private ApiInfo apiInfo(){
    //        public static final Contact DEFAULT_CONTACT = new Contact("", "", "");
    /*    
    static {
        DEFAULT = new ApiInfo("Api Documentation", "Api Documentation", "1.0", "urn:tos", DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
        */
    }
    // 设置联系人信息
    Contact contact = new Contact("丰", "https://www.baidu.com", "123123@qq.com");
    return new ApiInfo(
        "Api Documentation",   // 标题
        "Api Documentation",  //描述
        "1.0",   // 版本
        "urn:tos",   // 组织url
        contact,    // 联系人信息
        "Apache 2.0",   // 许可
        "http://www.apache.org/licenses/LICENSE-2.0",   // 许可url
        new ArrayList<>()  // 扩展
    );
}

添加 ApiInfo及其请求过滤

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())   //   将文档信息更改为我们自定义的
        // 配置扫描接口，
        .select().apis(RequestHandlerSelectors.basePackage("com.feng.controller"))
        // 过滤, 只匹配哪些请求, 相当于二次筛选（使用的是正则）
        .paths(PathSelectors.ant("/hello"))
        .build();
}

设置是否可访问

// 默认为true，改为false，在浏览器中不能够再打开此页面
// 项目上线时，需要关闭此功能（不能让用户看到后台的相关信息）
// 所有通常将其设置为动态的
.enable(false)  

环境配置

# 激活对应的环境
spring.profiles.active=test

# 测试环境
server.port=8080

# 项目发布环境
server.port=8081

@Bean
public Docket docket(Environment environment){
    
    Profiles test = Profiles.of("test", "dev");   // 设置要显示的环境,可以存在多个
    boolean b = environment.acceptsProfiles(test);   // 判断是否有选择该环境

    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())   //   将文档信息更改为我们自定义的
            .enable(b)    // 通过环境判断是否开启
            // 配置扫描接口，
            .select().apis(RequestHandlerSelectors.basePackage("com.feng.controller"))
            // 过滤, 只匹配哪些请求, 相当于二次筛选（使用的是正则）
            .paths(PathSelectors.ant("/hello"))
            .build();
}

分组配置， 设置多个Docket,每一个都是独立的

@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

注解信息

@Api(tags = “xxx模块说明”) 用在模块类上

@ApiOperation(“xxx接口说明”) 用在接口方法上

@ApiModel(“xxx实体类说明”) 用在实体类上

@ApiModelProperty(value = “xxx属性说明”,hidden = true) 用在方法/属性上，可以设置为是否隐藏

@ApiParam(“xxx参数说明”) 用在参数/方法上

@ApiModel("用户实体")
public class User {
    @ApiModelProperty(value = "用户名")
    private String username;
    @ApiModelProperty("密码", hidden = true)
    private String password;
}