接口管理

接口管理

YApi

一款api管理平台

源码地址

安装比较麻烦，和apifox功能差不多

Swagger

1. 导入坐标

   <!--Swagger-UI API文档生产工具-->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.9.2</version>
   </dependency>
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>2.9.2</version>
   </dependency>

2. 编写配置类

   @Configuration
   @EnableSwagger2
   public class Swagger2Config {
       @Bean
       public Docket createRestApi(){
           return new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(apiInfo())
               .select()
               //为当前包下controller生成API文档
               .apis(RequestHandlerSelectors.basePackage("com.xw.mallLearning.controller"))
               //为有@Api注解的Controller生成API文档
               //                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
               //为有@ApiOperation注解的方法生成API文档
               //                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
               .paths(PathSelectors.any())
               .build();
       }
   
       private ApiInfo apiInfo() {
           return new ApiInfoBuilder()
               .title("SwaggerUI")
               .description("mall-learning")
               .version("1.0")
               .build();
       }
   }

3. 当swagger版本大于2.6.x且springBoot版本也较高(我测试时是2.7.8)时，需要在配置类中添加以下Bean和配置

   @Bean
   public static BeanPostProcessor springfoxHandlerProviderBeanPostProcessor() {
       return new BeanPostProcessor() {
   
           @Override
           public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
               if (bean instanceof WebMvcRequestHandlerProvider) {
                   customizeSpringfoxHandlerMappings(getHandlerMappings(bean));
               }
               return bean;
           }
   
           private <T extends RequestMappingInfoHandlerMapping> void customizeSpringfoxHandlerMappings(List<T> mappings) {
               List<T> copy = mappings.stream()
                   .filter(mapping -> mapping.getPatternParser() == null)
                   .collect(Collectors.toList());
               mappings.clear();
               mappings.addAll(copy);
           }
   
           @SuppressWarnings("unchecked")
           private List<RequestMappingInfoHandlerMapping> getHandlerMappings(Object bean) {
               try {
                   Field field = ReflectionUtils.findField(bean.getClass(), "handlerMappings");
                   field.setAccessible(true);
                   return (List<RequestMappingInfoHandlerMapping>) field.get(bean);
               } catch (IllegalArgumentException | IllegalAccessException e) {
                   throw new IllegalStateException(e);
               }
           }
       };
   }

   spring:
     mvc:
       pathmatch:
         matching-strategy: ant_path_matcher

常用注解

使文档说明更加易读

注解	说明
@Api	用在请求类上(如Controller)，表示对类的说明
@ApiModel	用在实体类上，表示返回响应数据的信息
@ApiModelProperty	用在实体类属性上
@ApiOperation	用在请求的方法上，说明方法的用途
@ApiImplicitParams	用在请求的方法上，表示一组参数的说明
@ApiImplicitParam	用在@ApiImplicitParams中，指定一个参数的各个方面

knife4j

用来生成各种格式的接口文档

knife4j是集成swagger生成api文档的增强解决方案

使用步骤

1. 导入坐标

   <dependency>
       <groupId>com.github.xiaoymin</groupId>
       <artifactId>knife4j-spring-boot-starter</artifactId>
       <version>3.0.2</version>
   </dependency>

2. 导入配置类

   在mvc配置类上加入两个注解并构建createRestApi方法

   @Configuration
   @EnableSwagger2
   @EnableKnife4j
   public class WebMvcConfigSupport extends WebMvcConfigurationSupport {
       @Bean
       public Docket createRestApi() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .select()
                   .apis(RequestHandlerSelectors.basePackage("com.xw.reggie.controller"))
                   .paths(PathSelectors.any())
                   .build();
       }
   
       private ApiInfo apiInfo() {
           return new ApiInfoBuilder()
                   .title("瑞吉外卖")
                   .version("1.0")
                   .description("瑞吉外码接口文档")
                   .build();
       }
   }

3. 在mvc配置类的addResourceHandlers方法中设置静态资源映射

   registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
   registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");

4. 如果有登录状态检测的话要设置放行

   //放行的路径
   "/doc.html",
   "/webjars/**",
   "/swagger-resources",
   "/v2/api-docs"

5. 访问http://localhost:8080/doc.html可以查看接口和导出离线文档