java接口文档:springboot整合knife-4j，swaggerui基本注解

简介

knife简单来说为Swagger的UI增强版。和Swagger在代码上面的注解并没有太多不同，只需要做几个引入和配置即可。

写一个knife demo

1. 引入jar包

• 因为是Swagger的增强版，所以还是需要引入Swagger的jar包

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

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

2. 添加配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {

        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("这里是swagger的标题")
                .description("这里是描述内容")
                .contact(new Contact("Z", "", ""))
                .termsOfServiceUrl("http://localhost:18099/") //* 地址 用于显示 不会影响
                .version("1.0")
                .build();

        return new Docket(DocumentationType.SWAGGER_2)
                .host("http://localhost:28099/")//* 地址 用于显示 不会影响
                .groupName("后台接口")
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

3. 开放静态资源

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class IntercpetorConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 设置swagger静态资源访问
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

4. 启动项目，访问http://{ip}:{host}/doc.html 即可。

Swagger常用注解

1. @Api 描述接口类

• 使用位置: 接口类上面
• 参数:
  • tags：类名。可以传多个值。
  • description: 描述

      @Api(tags = {"文件接口"},description = "文件接口类")
      public class FileController {
      }
  

2. @ApiOperation 描述接口方法

• 使用位置: 写在方法上
• 参数:
  • value: 方法描述
  • notes: 提示信息

      @PostMapping("/resume")
      @ApiOperation(value = "续传接口",notes = "file对象从request中获取")
      public Map resume(HttpServletRequest req) throws Exception {
      }
  

3. @ApiParam 描述接口方法参数

• 使用位置: 写在方法参数上
• 参数:
  • name: 参数名称
  • value: 参数描述
  • required: 必填标志

      @PostMapping("/resume")
      @ApiOperation(value = "续传接口",notes = "file对象从request中获取")
      public Map resume(@ApiParam(name = "req",value = "request对象",required = true) HttpServletRequest req) throws Exception {
      }
  

4. @ApiModel 实体类描述

• 使用位置: 写在实体类上
• 参数:
  • value: 实体类名称
  • description: 实体类描述

      @ApiModel(value = "用户类",description = "用户实体类")
      public class User {
          @ApiModelProperty(value = "姓名",name =  "name",required =  true,example = "张三")
          String name;
          String password;
      }
  

5. @ApiModelProperty 实体类属性描述

• 使用位置: 写在实体类参数上
• 参数:
  • value: 描述
  • name: 属性名
  • required: 是否必填
  • hidden: 隐藏
  • example: 示例

      @ApiModel(value = "用户类",description = "用户实体类")
      public class User {
          @ApiModelProperty(value = "姓名",name =  "name",required =  true,example = "张三")
          String name;
          String password;
      }