演示环境
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文档
官网:knife4j
1、添加依赖
io.springfox
springfox-swagger2
3.0.0
com.github.xiaoymin
knife4j-spring-boot-starter
3.0.3
2、创建接口文档配置类 - SwaggerConfig.java
ps:类名可自定义,也可以在yml中配置,可自行参考knife4j的官方文档
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:这里是首页数据模型类,类的名称可以自定义,我这里的首页用于演示,实际开发以业务为准
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:这里是首页应答消息类,类的名称可以自定义,我这里的首页用于演示,实际开发以业务为准
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 需要你自己手动导一下包
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;
}
}
生成后,效果如下
6、启动项目,访问接口文档
knife4j的文档地址:springboot项目地址/doc.html
ps:也可以在这里调试接口
二、Apifox + Apifox Helper 插件
ps:需要创建 Model类、Message类 和 控制器类;描述要写到位,不然文档不会生成描述
1、下载 Apifox -> 注册 -> 登录
2、新建一个团队,名称自定义
3、新建一个项目,名称自定义
4、创建 API访问令牌
注意:点击生成后,会显示生成的令牌,一定要记住了再点击关闭,不然关闭后就无法查看了,那就只能重新创建一个令牌了
5、打开 IDEA,搜索 Apifox Helper 插件,并下载
6、下载完毕后,点击立即重启以生效
这时候在设置里面就能看到插件的配置项了
7、插件配置
8、获取项目ID
9、使用插件自动生成并上传文档到 Apifox
ps:在控制器中 或 右击控制器 用于生成单个控制器的接口文档
如果右击 controller 包,用于生成所有控制器的接口文档
ps:第一次上传需要输入 项目ID,然后点击 OK
ps:控制台会打印详细的日志信息,看到 Imported Successfully 表示上传成功
10、打开 Apifox 查看接口信息
至此,本教程完毕!
结语
希望对你能有所帮助,有问题可以私信或下方留言给我