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

news2025/3/31 12:11:41

文章目录

问题：Java项目生成接口文档的方案
- 方案一：`Swagger3.0`
- 方案二：`Apipost`
- 两者对比

问题：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", "2437690868@qq.com"))
                .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());
    }

}