接口管理——Swagger

颜妮儿2023-12-13 11:13

Swagger是一个用于设计、构建和文档化API的工具集。它包括一系列工具，如Swagger Editor（用于编辑Swagger规范）、Swagger UI（用于可视化API文档）和Swagger Codegen（用于根据API定义生成客户端库、server stubs等）。Swagger通过定义API的结构、参数、请求和响应格式等信息，帮助开发者更轻松地创建和管理API，并生成易于理解的文档。按照它的规范去定义接口及接口相关的信息，就可以做到生成接口文档，以及在线接口调试页面。官网地址：https://swagger.io/

与Postman相比：Swagger更关注API设计和文档化，而Postman更适合测试、调试、监视API。
Knife4j 是为Java MVC框架集成Swagger生成Api文档的增强解决方案。

使用：

在pom.xml中添加依赖（导入 knife4j 的maven坐标）：
<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>3.0.2</version> </dependency>

在配置类(WebMvcConfiguration)中加入 knife4j 相关配置

复制代码

/**
  * 通过knife4j生成接口文档
  * @return
  */
 @Bean
 public Docket docket() {
     log.info("准备生成接口文档......");
     ApiInfo apiInfo = new ApiInfoBuilder()
             .title("xxx项目接口文档")
             .version("2.0")
             .description("xxx项目接口文档")
             .build();
     Docket docket = new Docket(DocumentationType.SWAGGER_2)
             .apiInfo(apiInfo)
             .select()
             //指定生成接口需要扫描的包
             .apis(RequestHandlerSelectors.basePackage("这里填包名：AAA.BBB.CCC"))
             .paths(PathSelectors.any())
             .build();
     return docket;
 }

 /**
  * 设置静态资源映射
  * @param registry
  */
 protected void addResourceHandlers(ResourceHandlerRegistry registry) {
     log.info("开始设置静态资源映射......");
     registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
     registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
 }

当访问http://localhost:8080/doc.html时：

通过注解可以控制生成的接口文档，使接口文档拥有更好的可读性，常用注解如下：

添加这些注解的作用：