swagger-bootstrap-ui

依赖

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

swagger配置文件

/**
 * @author qm
 * @date 2021/3/8
 * <p>
 * json文件访问:
 * http://localhost:8080/v2/api-docs
 * <p>
 * json转换为word:
 * https://tools.kalvinbg.cn/dev/swagger2word
 */
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("1")
                .description("2")
                .version("3")
                .build();
    }
}

地址访问

1. json文件访问:
   http://localhost:8080/v2/api-docs

2. json转换为word:
   https://tools.kalvinbg.cn/dev/swagger2word

3. swagger访问：
   http://localhost:8080/doc.html

注意事项

1. 如果配置了项目主路径，还要带上哟
2. 如果是用到了shiro框架，需要这样做，注意filterChainDefinitionMap.put("/**", "authc");需要放在最后一行，否则不行

           //不拦截swagger的访问
           filterChainDefinitionMap.put("/doc.html", "anon");
           filterChainDefinitionMap.put("/swagger-resources", "anon");
           filterChainDefinitionMap.put("/swagger-resources/configuration/security", "anon");
           filterChainDefinitionMap.put("/swagger-resources/configuration/ui", "anon");
           filterChainDefinitionMap.put("/v2/api-docs", "anon");
           filterChainDefinitionMap.put("/webjars/**", "anon");
   
           filterChainDefinitionMap.put("/**", "authc");

   但是这样所只能做到swagger能访问查看，数据接口依然被shiro拦截了，无法在swagger上面进行调试，此时可以这样做：
   1. yml文件配置，表示环境为开发环境，可以访问swagger文档，生成环境改为true就会禁止访问

      swagger:
        production: false

   2. ShiroConfig文件中引入swagger.production变量，使用改变量判断是否拦击数据接口（其它关于swagger的拦截就不需要了）

          @Value("${swagger.production}")
          private boolean production;
      
          @Bean
          public ShiroFilterFactoryBean shirFilter(SecurityManager securityManager) {
               ... ...
              //如果是生成环境则启用数据接口拦截，否则不拦截，这样可以方便在swagger上面测试接口
              if(production){
                  //放在最后的put行，其它关于swagger的拦截就不需要了
                  filterChainDefinitionMap.put("/**", "authc");
              }
              ... ...
          }

      这样子就可以在swagger测试所有数据接口了。

       

3. swagger页面导航栏出没有显示地址怎么办？
   
   
4. 有时候左侧的导航栏没有数据了是怎么回事儿？
   更换端口可能导致没有数据，清空浏览器缓存即可

全局code码配置

枚举code

public enum CommonExceptionEnum {

    /**
     * 请求成功
     */
    SUCCESS(200, "操作成功"),

    /**
     * 默认失败
     */
    DEFAULT_ERROR(90001, "请求异常"),

    /**
     * 参数验证类
     */
    PARAM_ERROR(10001, "请求参数不正确"),

    /**
     * 项目业务类
     */
    DATA_NOT_EXIST_ERROR(20001, "请求数据不存在"),
    DATA_EXIST_ERROR(20002, "数据已存在"),
    /**
     * 用户登录时，发现多个用户名相同的用户
     */
    ACCOUNT_ALREADY_EXIST(20003, "用户数据有误，请联系管理员检查用户数据"),
    /**
     *  账号未启用
     */
    ACCOUNT_DISABLED(20004, "账号未启用"),
    /**
     *  账号未启用
     */
    ACCOUNT_NOT_EXIST(20005, "账号不存在"),


    /**
     * 权限类
     */
    NO_LOGIN(50001, "用户未登录或者session过期"),
    NO_PERMISSION(50002, "没有权限");


    /**
     * result Code
     */
    private final int resultCode;
    /**
     * result message
     */
    private final String resultMsg;

    public int getResultCode() {
        return resultCode;
    }

    public String getResultMsg() {
        return resultMsg;
    }


    CommonExceptionEnum(int resultCode, String resultMsg) {
        this.resultCode = resultCode;
        this.resultMsg = resultMsg;
    }
}

 

 

配置全局swagger code

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        //添加全局响应状态码
        List<ResponseMessage> responseMessageList = new ArrayList<>();
        Arrays.stream(CommonExceptionEnum.values()).forEach(errorEnums -> {
            responseMessageList.add(
                    new ResponseMessageBuilder().code(errorEnums.getResultCode()).message(errorEnums.getResultMsg()).responseModel(
                            new ModelRef(errorEnums.getResultMsg())).build()
            );
        });

        return new Docket(DocumentationType.SWAGGER_2)
                // 添加全局响应状态码
                .globalResponseMessage(RequestMethod.GET, responseMessageList)
                .globalResponseMessage(RequestMethod.POST, responseMessageList)
                .globalResponseMessage(RequestMethod.PUT, responseMessageList)
                .globalResponseMessage(RequestMethod.DELETE, responseMessageList)

                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("")
                .description("")
                .version("")
                .build();
    }

}

效果

这样不用在controller上写注解@ApiResponses、@ApiResponse了，效果如下