演示环境

springboot：2.5.2

jdk：1.8

springfox-swagger2：3.0.0

knife4j-spring-boot-starter：3.0.3

一、Swagger2 + Knife4j

1、Swagger2：用于设计、构建和文档化RESTful API的开源框架

2、Knife4j：基于Swagger构建的开源API文档工具，它提供了一套简洁美观的UI界面，可以更好地呈现和管理API文档

1、添加依赖

java 复制代码

	<!-- swagger2依赖 -->
	<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>3.0.0</version>
        </dependency>

	<!-- knife4j依赖 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.3</version>
        </dependency>

2、创建接口文档配置类 - SwaggerConfig.java

ps：类名可自定义，也可以在yml中配置，可自行参考knife4j的官方文档

java 复制代码

import io.swagger.annotations.Api;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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 SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .build()
                .groupName("默认分组");
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .contact(new Contact(
                        "作者名称",
                        "作者个人网站地址",
                        "作者邮箱"
                ))
                .title("karl-接口文档标题")
                .description("karl的接口文档描述")
                .version("1.0.0")
                .termsOfServiceUrl("接口服务地址")
                .build();
    }
}

生成后，效果如下

3、新建数据模型类 - IndexModel.java

ps：这里是首页数据模型类，类的名称可以自定义，我这里的首页用于演示，实际开发以业务为准

java 复制代码

import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.ApiParam;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;

// 这里使用了 lombok
// 也可以使用原始的方式用IDEA生成这些方法
// 包括：无参构造函数、get方法、set方法
@NoArgsConstructor
@Getter
@Setter
public class IndexModel {

    // 属性描述
    @ApiModelProperty("用户输入的字符串")
    // 隐藏该参数，便于在控制器中用 @ApiImplicitParam 来控制文档显示的请求参数
    @ApiParam(hidden = true)
    private String str;

}

生成后，效果如下

4、新建应答消息类 - IndexMessage.java

ps：这里是首页应答消息类，类的名称可以自定义，我这里的首页用于演示，实际开发以业务为准

java 复制代码

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.ApiParam;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;

// 这里使用了 lombok
// 也可以使用原始的方式用IDEA生成这些方法
@NoArgsConstructor
@Getter
@Setter
// 模型对象描述
@ApiModel(value = "首页接口返回信息")
public class IndexMessage {

    // 属性描述
    @ApiModelProperty("返回的字符串内容")
    // 隐藏该参数
    @ApiParam(hidden = true)
    private String resultStr;

}

生成后，效果如下

5、新建首页控制器 - IndexController.java

ps：这里是首页控制器类，类的名称可以自定义，我这里的首页用于演示，实际开发以业务为准

注意：IndexModel 和 IndexMessage 需要你自己手动导一下包

java 复制代码

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

// 接口文档一级菜单标题
@Api(tags = {"首页"})
@RestController
// 一级请求路径
@RequestMapping("/Index")
public class IndexController {

    // 接口文档二级菜单标题、说明
    @ApiOperation(value = "首页演示接口", notes = "首页-HelloWorld-接口说明")
    // 接口的请求参数，可以根据 Model类的属性随意控制
    // 但是要根据实际业务来，本接口需要哪些参数就写哪些
    @ApiImplicitParams({
            @ApiImplicitParam(name = "str", value = "用户输入的字符串", paramType = "query", required = true)
    })
    // 二级请求路径
    @PostMapping("/HelloWorld")
    // 接口方法
    // 参数：IndexModel - 首页请求数据模型类
    // 返回：IndexMessage - 首页应答消息类
    public IndexMessage HelloWorld(IndexModel indexModel) throws Exception {
        // 创建 首页应答消息对象
        IndexMessage message = new IndexMessage();
        // 将 用户传入的字符串 与 helloWorld 拼接，并赋值给应答对象的属性
        message.setResultStr("helloWorld " + indexModel.getStr());
        // 返回 首页应答消息对象
        return message;
    }

}