java接口文档 springboot整合knife-4j，

发表于
简介

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

写一个knife demo
  1. 引入jar包
  • 因为是Swagger的增强版，所以还是需要引入Swagger的jar包
1
2
3
4
5
6
7
8
9
10
11
xml复制代码<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>
  1. 添加配置类
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
java复制代码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();
    }
}
  1. 开放静态资源
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
java复制代码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/");
    }
}
  1. 启动项目，访问http://{ip}:{host}/doc.html 即可。
Swagger常用注解
  1. @Api 描述接口类
  • 使用位置: 接口类上面
  • 参数:
    • tags：类名。可以传多个值。
    • description: 描述
      1
      2
      3
      java复制代码    @Api(tags = {"文件接口"},description = "文件接口类")
          public class FileController {
          }
  1. @ApiOperation 描述接口方法
  • 使用位置: 写在方法上
  • 参数:
    • value: 方法描述
    • notes: 提示信息
      1
      2
      3
      4
      java复制代码    @PostMapping("/resume")
          @ApiOperation(value = "续传接口",notes = "file对象从request中获取")
          public Map resume(HttpServletRequest req) throws Exception {
          }
  1. @ApiParam 描述接口方法参数
  • 使用位置: 写在方法参数上
  • 参数:
    • name: 参数名称
    • value: 参数描述
    • required: 必填标志
      1
      2
      3
      4
      java复制代码    @PostMapping("/resume")
          @ApiOperation(value = "续传接口",notes = "file对象从request中获取")
          public Map resume(@ApiParam(name = "req",value = "request对象",required = true) HttpServletRequest req) throws Exception {
          }
  1. @ApiModel 实体类描述
  • 使用位置: 写在实体类上
  • 参数:
    • value: 实体类名称
    • description: 实体类描述
      1
      2
      3
      4
      5
      6
      java复制代码    @ApiModel(value = "用户类",description = "用户实体类")
          public class User {
              @ApiModelProperty(value = "姓名",name =  "name",required =  true,example = "张三")
              String name;
              String password;
          }
  1. @ApiModelProperty 实体类属性描述
  • 使用位置: 写在实体类参数上
  • 参数:
    • value: 描述
    • name: 属性名
    • required: 是否必填
    • hidden: 隐藏
    • example: 示例
      1
      2
      3
      4
      5
      6
      java复制代码    @ApiModel(value = "用户类",description = "用户实体类")
          public class User {
              @ApiModelProperty(value = "姓名",name =  "name",required =  true,example = "张三")
              String name;
              String password;
          }

本文转载自: 掘金

开发者博客 – 和开发相关的 这里全都有

0%