基于Swagger的Knife4j，值得拥有

一、介绍Knife4j

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。
参考文档

swagger配置

二、基础搭建

1、pom依赖

    <io.swagger.version>1.5.21</io.swagger.version>
    <swagger2.version>2.9.2</swagger2.version>
    <knife4j.version>2.0.2</knife4j.version>
    
<!-- 引入 spring-boot -swagger 并生成优美的API文档 -->
      <!-- swagger start -->
      <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>${io.swagger.version}</version>
      </dependency>
      <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-models</artifactId>
        <version>${io.swagger.version}</version>
      </dependency>
      <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${swagger2.version}</version>
      </dependency>
      <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${swagger2.version}</version>
      </dependency>
      <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
        <version>${knife4j.version}</version>
      </dependency>
      <!-- swagger end -->

2、configuration

2.1、SwaggerProperties

@Data
@ConfigurationProperties(prefix = "swagger")
@Component
public class SwaggerProperties {
  /**
   * 是否启用
   */
  private boolean enabled;
  /**
   * 标题
   */
  private String title;

  /**
   * 文档描述
   */
  private String description;

  /**
   * 项目路径
   */
  private String termsOfServiceUrl;

  /**
   * 作者
   */
  private String authorName;

  /**
   * 邮箱
   */
  private String authorEmail;

  /**
   * 作者主页
   */
  private String authorUrl;

  /**
   * 版本
   */
  private String version;

  /**
   * web扫描的路径
   */
  private String webBasePackage;

  /**
   * API扫描的路径
   */
  private String apiBasePackage;
}

2.2、路径扫描配置InterceptorProperties

@Data
@ConfigurationProperties(prefix = "xiu-core.auth.interceptor")
@Component
public class InterceptorProperties {

  /**
   * 是否启用
   */
  private boolean enable;

  /**
   * 包含的路径
   */
  private String[] includePaths = new String[]{};

  /**
   * 排除路径
   */
  private String[] excludePaths = new String[]{};
}

2.3、configuration配置SwaggerConfiguration

@Configuration
@EnableSwagger2
@EnableConfigurationProperties(value = SwaggerProperties.class)
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
@ConditionalOnProperty(value = {"swagger.enabled"}, matchIfMissing = true)
public class SwaggerConfiguration {

  @Bean(value = "restWeb")
  public Docket createRestWeb(SwaggerProperties swaggerProperties) {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(
            new ApiInfoBuilder()
                .title(swaggerProperties.getTitle())
                .description(swaggerProperties.getDescription())
                .termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())
                .contact(new Contact(swaggerProperties.getAuthorName(),
                    swaggerProperties.getAuthorUrl(),
                    swaggerProperties.getAuthorEmail()))
                .version(swaggerProperties.getVersion())
                .build()).groupName("后台 Web")
        .select()
        .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getWebBasePackage()))
        .paths(PathSelectors.any())
        .build();
  }

  @Bean(value = "restApi")
  public Docket createRestApi(SwaggerProperties swaggerProperties) {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(
            new ApiInfoBuilder()
                .title(swaggerProperties.getTitle())
                .description(swaggerProperties.getDescription())
                .termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())
                .contact(new Contact(swaggerProperties.getAuthorName(),
                    swaggerProperties.getAuthorUrl(),
                    swaggerProperties.getAuthorEmail()))
                .version(swaggerProperties.getVersion())
                .build()).groupName("前台 Api")
        .select()
        .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getApiBasePackage()))
        .paths(PathSelectors.any())
        .build();
  }
}

三、项目引用

3.1、配置项目属性

# Swagger配置
swagger:
  enabled: true
  title: 接口文档
  description: 描述
  termsOfServiceUrl: 地址
  authorName: Mr.xiu
  authorEmail: [email protected]
  authorUrl: 地址
  version: 1.0.1
  webBasePackage: com.xiu.lawyer.web.controller.admin
  apiBasePackage: com.xiu.lawyer.web.controller.index

# knife开源的swagger ui配置
knife4j:
  # 配置认证功能
  basic:
    # 是否开启认证
    enable: true
    # 用户名
    username: admin
    # 密码
    password: 123456

3.2、拦截器及资源配置

  /**
   * 拦截器配置
   *
   * @param registry
   */
  @Override
  public void addInterceptors(InterceptorRegistry registry) {
    //权限拦截器
    if (interceptorConfig.isEnable()) {
      registry.addInterceptor(authenticationInterceptor())
          .addPathPatterns(interceptorConfig.getIncludePaths())
          .excludePathPatterns(interceptorConfig.getExcludePaths());
    }
  }
  /**
   * 资源映射
   *
   * @param registry
   */
  @Override
  public void addResourceHandlers(ResourceHandlerRegistry registry) {
    if (swaggerProperties.isEnabled()) {
      registry.addResourceHandler("doc.html","swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
      registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
  }

四、页面展示


完！