【框架1-springboot整合Knife4j框架-API文档框架】

最新推荐文章于 2024-05-03 04:49:12 发布

稻谷-2029

最新推荐文章于 2024-05-03 04:49:12 发布

阅读量687

点赞数

本文链接：https://blog.csdn.net/m0_55355196/article/details/129729888

版权

3、配置application.yml,启动knife4j

一、简介

Knife4j是一款基于Swagger 2的在线API文档框架。，可以显示当前程序中指定路径下包含的接口，且可以生成接口doc文档.。

图示

当输入（http://localhost:8080/doc.html）时会跳转到该页面

二、框架使用

1、引入依赖

 <!-- Knife4j Spring Boot：在线API -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.9</version>
        </dependency>

2、配置config

注意修改basePackage 为指定controller路径

package com.zy.kjxx.config;

import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
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.EnableSwagger2WebMvc;

/**
 * Knife4j配置类
 *
 * @author java@tedu.cn
 * @version 0.0.1
 */
@Slf4j
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {
    /**
     * 【重要】指定Controller包路径
     */
    private String basePackage = "com.zy.kjxx.controller";
    /**
     * 分组名称
     */
    private String groupName = "product";
    /**
     * 主机名
     */
    private String host = "http://java.ZY.cn";
    /**
     * 标题
     */
    private String title = "ZY项目API管理";
    /**
     * 简介
     */
    private String description = "ZY项目API文档--API管理";
    /**
     * 服务条款URL
     */
    private String termsOfServiceUrl = "http://www.apache.org/licenses/LICENSE-2.0";
    /**
     * 联系人
     */
    private String contactName = "Java教学研发部";
    /**
     * 联系网址
     */
    private String contactUrl = "http://java.ZY.cn";
    /**
     * 联系邮箱
     */
    private String contactEmail = "999999999@qq.com";
    /**
     * 版本号
     */
    private String version = "1.0.0";

    @Autowired
    private OpenApiExtensionResolver openApiExtensionResolver;

    public Knife4jConfiguration() {
        log.debug("创建配置类对象：Knife4jConfiguration");
    }

    @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();
    }
}

3、配置application.yml,启动knife4j

knife4j:
  enable: true

4、设置端口

package cn.tedu.csmall.product.controller;

import cn.tedu.csmall.product.ex.ServiceException;
import cn.tedu.csmall.product.pojo.dto.AlbumAddNewDTO;
import cn.tedu.csmall.product.service.IAlbumService;
import com.github.xiaoymin.knife4j.annotations.ApiOperationSupport;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;

import javax.servlet.http.HttpSession;

@RestController
@RequestMapping("/album")
@Api(tags = "01. 相册管理模块")

public class AlbumController {

    @Autowired
    private IAlbumService albumService;

    // http://localhost:9080/album/add-new?name=TestName001&description=TestDescription001&sort=199
    @PostMapping("/add-new")
    @ApiOperation("添加相册")
    @ApiOperationSupport(order = 100)
    public String addNew( AlbumAddNewDTO albumAddNewDTO) {
        albumService.addNew(albumAddNewDTO);
        return "添加相册成功！";
    }

    @PostMapping("/delete")
    @ApiOperation("根据ID删除相册")
    @ApiOperationSupport(order = 200)
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "id", value = "相册ID", required = true, dataType = "long")
    })
    public String delete(Long id) {
        return "模拟删除相册成功！";
    }

    @PostMapping("/update")
    @ApiOperation("修改相册")
    @ApiOperationSupport(order = 300)
    public void update(@ApiIgnore HttpSession session) {
        // 由adminService调用修改方法，Service中的方法仍可能抛出异常
        throw new ServiceException("测试修改相册时，假设抛出的异常");
    }

}

5、进入doc.html

http://localhost:8005/doc.html

三、框架配置

1、菜单项设置

@Api(tags="01.相册管理模块")

添加到类上，设置菜单项名字

2、菜单子项设置

@PostMapping("/add-new") //对应post,可修改为GetMapping等
@ApiOperation("添加相册")  //对应菜单子项名称
@ApiOperationSupport(order = 100)  //显示的位置，越小越靠前

添加到方法上，对应菜单子项显示的请求方式（Post）,名字，和显示先后顺序

3、请求参数设置

A.请求的是对象

Value是描述参数，required是是否必须，example是示例值和默认值

@Data
public class AlbumAddNewDTO implements Serializable {

    //value参数说明   required是否必须   example 实例值
    @ApiModelProperty(value = "相册名称", required = true, example = "格力空调的相册")
    private String name;

    @ApiModelProperty(value = "相册简介", required = true)
    private String description;

    @ApiModelProperty(value = "排序序号", required = true, example = "99")
    private Integer sort;

}

注：

1、此处如果配置了required=true，只是一种显示效果，Knife4j框架并不具备检查功能

2、如果需要配置example，必须保证配置值是可以被转换成实际所需的值！例如sort的值必须是数值类型的，配置此属性的example值必须保证是纯数字的！

B.请求的是变量

@ApiImplicitParam 用在方法上，用于配置处理请求的方法的参数

@ApiImplicitParams 有多个参数使用这个

@PostMapping("/delete")
    @ApiOperation("根据ID删除相册")
    @ApiOperationSupport(order = 200)
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "id", value = "相册ID", required = true, dataType = "long")
    })
    public String delete(Long id) {
        return "模拟删除相册成功！";
    }

C.没有参数

@ApiIgnore表示忽略参数

//@ApiIgnore表示忽略该参数
public void update(@ApiIgnore HttpSession session) {}

四、生成离线文档

末、字段明晰

@Api：添加在控制器类上，通过此注解的tags属性，可以配置模块名称
@ApiOpeartion：添加在处理请求的方法上，通过此注解的value属性，可以配置业务名称
@ApiOperationSupport：添加在处理请求的方法，通过此注解的order属性（数值类型），可配置业务的排序序号，在显示多个业务时，将按照此值升序排列
@ApiModelProperty：添加在POJO类型的属性上，对请求参数或响应的数据属性进行描述配置，通过此注解的value属性，可以配置参数名称，通过此注解的required属性，可以配置“是否必须提交此请求参数”，通过此注解的example属性，可以配置参数的“示例值”
- 注意：此处如果配置了required=true，只是一种显示效果，Knife4j框架并不具备检查功能
- 注意：如果需要配置example，必须保证配置值是可以被转换成实际所需的值！例如sort的值必须是数值类型的，配置此属性的example值必须保证是纯数字的！
@ApiImplicitParam：添加在处理请求的方法上，用于配置处理请求的方法的参数（通常是简单数据类型的）的描述，使用此注解配置时，必须先使用name属性指定参数名称（参数的变量名），然后，再通过value属性配置参数的描述，并按需使用dataType指定数据类型（一旦使用此注解，各参数的数据类型默认都会显示为string），另外，也可以通过此注解的required属性，可以配置“是否必须提交此请求参数”，通过此注解的example属性，可以配置参数的“示例值”
@ApiImplicitParams：添加在处理请求的方法上，如果此方法需要使用多个@ApiImplicitParam注解对多个参数进行描述说明，则多个@ApiImplicitParam必须作为当前注解的参数值
@ApiIgnore：添加在处理请求的方法的参数上，用于表示API文档框架应该“忽略”此参数