Java项目生成接口文档的方案

问题：Java项目生成接口文档的方案

需求

1、需要生成生成时间，作者名称，项目名称，接口名称，请求参数，请求地址，请求类型，请求用例，请求方式，相应参数，响应用例。

2、需要生成markdown文档。

方案一：Swagger3.0

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。它提供了一套工具来帮助开发者设计、构建、文档化以及使用 RESTful API。

关键注解

@Api(tags = "后台管理")	说明：该控制器名称为后台管理
@ApiOperation	说明：置于接口名称上面，标识接口涵义

依赖：Java项目中添加依赖坐标

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version>
</dependency>
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version>
</dependency>

添加配置：Java项目中添加配置类

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;@Configuration
public class SwaggerConfig {@Bean(value = "defaultApi2")public Docket customDocket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).build();}/*** 构建 api文档的详细信息函数** @return*/private ApiInfo apiInfo() {return new ApiInfoBuilder().title("springboot-swagger2-demo").version("1.0.0").description("SpringBoot 集成 Swagger2 构建RESTful API").contact(new Contact("geekmice", "http://geekmice.cn", "[e-mail]")).build();}
}

添加注解：在控制器类和方法上添加 Swagger 注解

package com.example.demo.controller;import com.example.demo.entity.Goods;
import com.example.demo.entity.GoodsVO;
import com.example.demo.entity.GoodsDTO;
import com.example.demo.service.GoodsService;
import com.example.demo.utils.R;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import com.baomidou.mybatisplus.core.metadata.IPage;
import lombok.RequiredArgsConstructor;import java.util.Objects;/*** @Author pmb* @Desc (Goods)表控制层* @Date 2025-03-27 11:27:46*/
@RestController
@RequestMapping("goods")
@RequiredArgsConstructor
@Api(tags = "后台管理")
public class GoodsController {private final GoodsService goodsService;@ApiOperation("分页查询")@PostMapping("/queryByPage")public R<IPage<GoodsVO>> queryByPage(@RequestBody GoodsDTO param) {return goodsService.queryByPage(param);}@ApiOperation("根据ID查询")@PostMapping("/queryById")public R<GoodsVO> queryById(@RequestBody GoodsDTO param) {return goodsService.queryById(param.getId());}@ApiOperation("新增")@PostMapping("/insert")public R insert(@RequestBody Goods param) {return goodsService.insert(param);}@ApiOperation("根据id修改")@PostMapping("/update")public R update(@RequestBody Goods param) {if (Objects.isNull(param.getId())) {return R.failed("ID不能为空");}return goodsService.update(param);}@ApiOperation("根据id删除")@PostMapping("/deleteById")public R deleteById(@RequestBody GoodsDTO param) {return goodsService.deleteById(param.getId());}}

启动项目

访问文档

启动项目后，访问 http://localhost:8080/doc.html 即可查看生成的接口文档。

如何导出接口文档markdown

访问地址http://localhost:8080/doc.html#/home之后

点击左侧文档管理-》离线文档

导出四种类型的文档，pdf还未实现。

下载之后，如下图，四种方式

方案二：Apipost

Apipost 是一款功能强大的 API 调试与管理工具，集 API 设计、调试、文档生成等多种功能于一体，能够帮助开发者更高效地进行 API 相关的开发与测试工作。

接口编写完成之后，打开Apipost，对已完成的接口添加测试

现在对demo目录中的接口进行导出

点击demo项目右侧三个点，分享，复制地址

到达接口文档待导出界面

点击右侧，导出文档按钮，选择导出markdown

生成具体md文档

两者对比

	生成时间	作者名称	项目名称	接口名称	请求参数	请求示例	请求方式	响应参数	响应示例	生成md
方案一	0	1	1	1	1	0	1	1	0	1
方案二	1	1	1	1	0	1	1	0	1	1