swagger和knife4j使用实例

目录

1，POM依赖

2，编写配置文件

3，添加注解

4，访问http://127.0.0.1:8098/swagger-ui.html

5,常用注解说明

6,Knife4j 配置

---

先配置出原始的swagger界面.

Swagger 是一个规范和完整的框架，用于描述、生成、使用和可视化 RESTful 风格的 Web 服务。使后端可以很方便的调试接口.

1，POM依赖

引入swagger一般都要引入web相关的依赖的,但是swagger有很多spring相关的依赖会和web冲突,需要排除掉.

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <exclusions>
                <exclusion>
                    <artifactId>spring-context</artifactId>
                    <groupId>org.springframework</groupId>
                </exclusion>
                <exclusion>
                    <artifactId>spring-core</artifactId>
                    <groupId>org.springframework</groupId>
                </exclusion>
                <exclusion>
                    <artifactId>spring-beans</artifactId>
                    <groupId>org.springframework</groupId>
                </exclusion>
                <exclusion>
                    <artifactId>slf4j-api</artifactId>
                    <groupId>org.slf4j</groupId>
                </exclusion>
                <exclusion>
                    <artifactId>spring-aop</artifactId>
                    <groupId>org.springframework</groupId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <version>2.4.5</version>
        </dependency>

2，编写配置文件

注意要将cvs.controller写成自己的项目controller路径,enable的参数可以从配置文件中获取,用于开启和关闭swagger功能.

package cvs.config;

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.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() {
        return new Docket(DocumentationType.SWAGGER_2).enable(true)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("cvs.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .title("SpringBoot整合Swagger")
                        .description("SpringBoot整合Swagger,test!!!!!!")
                        .version("9.0")
                        .contact(new Contact("金龙","wangjinlong.xin","123@qq.com"))
                        .license("The Apache License")
                        .licenseUrl("http://www.baidu.com")
                        .build());
    }
}

3，添加注解

@Api     @ApiOperation    @ApiParam

package io.bkc.test.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/test")
@Api(tags = "/测试API")
public class TestController {

    @GetMapping("/test123")
    @ApiOperation("测试接口")
    public String test123(@RequestParam("id") String id){
        return "123";
    }
}

4，访问http://127.0.0.1:8098/swagger-ui.html

​ 

5, 常用注解说明

1. @Api: 用于类上，表示这个类是一个 Swagger 的资源。

   • value: 定义资源的名称。
   • tags: 定义标签，可以用来分组资源。
   • description: 对资源的简短描述。

2. @ApiOperation: 用于方法上，描述一个操作（API 方法）。

   • value: 操作的简要描述。
   • notes: 操作的详细描述。
   • response: 返回的类型。
   • httpMethod: HTTP 方法，如 GET、POST、PUT、DELETE 等。

3. @ApiResponses: 用于方法上，描述操作可能的响应。

   • value: 包含一个或多个 @ApiResponse 注解。

4. @ApiResponse: 用于 @ApiResponses 内部，描述一个特定的响应代码。

   • code: HTTP 响应代码。
   • message: 响应的简短描述。
   • response: 响应的类。

5. @ApiModel: 用于类上，表示这个类是一个 Swagger 模型。

   • description: 对模型的简短描述。

6. @ApiModelProperty: 用于属性上，描述模型属性。

   • value: 属性的简短描述。
   • name: 属性的名称。
   • required: 指示属性是否必需。
   • example: 属性的示例值。

7. @ApiParam: 用于方法参数上，描述一个操作参数。

   • value: 参数的简短描述。
   • required: 指示参数是否必需。

8. @ApiResponse: 用于描述一个特定的响应消息。

   • code: 响应的 HTTP 状态码。
   • message: 响应的消息。
   • response: 响应的类。

9. @ApiIgnore: 用于类、方法或参数上，指示 Swagger 忽略这个元素

6, Knife4j 配置

Knife4j 是 Swagger 生态系统中的一个补充工具，它基于 Swagger 的规范，但提供了更加丰富和定制化的用户体验。如果你已经在使用 Swagger，你可以无缝地切换到 Knife4j，以获得更好的 API 文档管理和展示功能。

修改pom依赖,去除原本的两个swagger依赖,添加下面的Knife4j依赖

<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
   <version>4.3.0</version>
   <exclusions>
      <exclusion>
         <artifactId>spring-aop</artifactId>
         <groupId>org.springframework</groupId>
      </exclusion>
      <exclusion>
         <artifactId>spring-beans</artifactId>
         <groupId>org.springframework</groupId>
      </exclusion>
      <exclusion>
         <artifactId>spring-context</artifactId>
         <groupId>org.springframework</groupId>
      </exclusion>
     </exclusions>
 </dependency>

 修改配置文件,只有注解变了,变成@EnableSwagger2WebMvc了

@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).enable(true)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("io.bkc.test.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .title("SpringBoot整合Swagger")
                        .description("SpringBoot整合Swagger,test!!!!!!")
                        .version("9.0")
                        .contact(new Contact("金龙","wangjinlong.xin","123@qq.com"))
                        .license("The Apache License")
                        .licenseUrl("http://www.baidu.com")
                        .build());
    }
}

 访问网页http://127.0.0.1:8098/swagger-ui.html,原本的访问地址是swagger-ui.html现在是doc.html

​