Uso del marco de documentación de la API en línea de Knife4j en SpringBoot

Tabla de contenido

1. Acerca de Knife4j

Knife4j es un marco de documentación de API en línea basado en Swagger 2.

2. Uso básico

2.1 Agregar dependencias al proyecto

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

(Nota) Las dependencias anteriores solo se aplican a versiones anteriores a Spring Boot 2.6 (no incluidas).

2.2 Habilitar el modo mejorado en el archivo de configuración

Agregue application.properties:

knife4j.enable=true

2.3 Clase de configuración personalizada

Cree Knife4jConfiguration.class en la carpeta de configuración del proyecto (la clase de configuración creada por usted mismo para almacenar el proyecto) y agregue la configuración:

El código de configuración es relativamente fijo

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

   
    //指定Controller包路径
    private String basePackage = "com.example.demo.controller";
    
    //分组名称
    private String groupName = "product";
    
    //主机名
    private String host = "http://localhost";
    
    //标题
    private String title = "Demo在线API文档";
    
    //简介
    private String description = "Demo在线API文档";

    //服务条款URL
    private String termsOfServiceUrl = "http://www.apache.org/licenses/LICENSE-2.0";
    
    //联系人
    private String contactName = "xxx";
    
    //联系网址
    private String contactUrl = "http://localhost";
    
    //联系邮箱
    private String contactEmail = "[email protected]";
    
    //版本号
    private String version = "1.0.0";

    @Autowired
    private OpenApiExtensionResolver openApiExtensionResolver;

    @Bean
    public Docket docket() {
        String groupName = "1.0.0";
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .host(host)
                .apiInfo(apiInfo())
                .groupName(groupName)
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build()
                .extensions(openApiExtensionResolver.buildExtensions(groupName));
        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .termsOfServiceUrl(termsOfServiceUrl)
                .contact(new Contact(contactName, contactUrl, contactEmail))
                .version(version)
                .build();
    }

}

2.4 acceso

Abra el navegador e ingrese http://localhost:8080/doc.html para acceder. (utilice la dirección y la interfaz configurada por el proyecto)

3. Configuración detallada

1) Agregue la anotación `@Api a la clase del controlador , configure el atributo `tags` y especifique el nombre del módulo (el nombre que se muestra en el menú de primer nivel en el documento API

2) Agregue la anotación @ApiOperation al método de procesamiento de la solicitud , configure el atributo de valor y especifique el nombre comercial (el nombre que se muestra en el subelemento del menú de primer nivel en el documento API)

3) Agregue la anotación @ApiOperationSupport` al método de procesamiento de la solicitud , configure el atributo `order` , y el valor es un valor, puede especificar el número de clasificación de visualización de la empresa, y se organizará en orden ascendente según al valor del atributo de orden

ejemplo:

@Api(tags = "轮播图管理模块")
@RestController
@RequestMapping("/banners")
public class BannerController {
    @Autowired
    private IBannerService iBannerService;
   
    @ApiOperation("添加轮播图")
    @ApiOperationSupport(order=101)
    @PostMapping("/addBanner")
    public JsonResult addNewBanner(@RequestBody BannerDTO bannerDto){
        iBannerService.addNewBanner(bannerDto);
        return JsonResult.ok();
    }
}

4) Agregue la anotación @ApiModelProperty al atributo del parámetro POJO del método que procesa la solicitud , configure el atributo de valor y especifique la descripción del parámetro. Además, también puede configurar si este parámetro es requerido a través del requerido atributo de la anotación (no tiene la función de verificación, solo se muestra en los documentos de la API como un envío obligatorio)

@Data
public class BannerDTO implements Serializable { 

    @ApiModelProperty(value="图片地址",required = true,example ="xxx")
    private String imgUrl;
}