springboot生成多页word文档

转载

mob64ca14144dde 2024-09-13 16:11:15

文章标签 spring boot 后端 java spring 实体类 文章分类 架构后端开发

根据SpringBoot项目生成接口文档

添加引用
配置生成开关
在实体类中添加注解
在控制类中添加注解
创建SpringDoc配置类
生成接口文档

开篇之前的碎碎念，之前使用的java8完成了项目的部分功能，重启电脑后，好多引用报红，然后就换成了java17，SpringBoot使用了3.2.2，过程中的痛苦折磨就不说了，故本文是基于SpringBoot 3.2.2生成接口文档。

以前有使用过Swagger2和Swagger3，一开始也是想用Swagger3生成接口文档的，使用Springfox写了一部分试了下，发现Springfox的Swagger3不支持SpringBoot3，所以就使用了SpringDoc生成。

添加引用

在pom.xml中添加

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-common</artifactId>
    <version>2.3.0</version>
</dependency>

配置生成开关

接口文档是在开发环境中使用的，如果是生成环境就不需要了，所以需要个开关控制。
在applicaiton.properties或application.yml中配置：

springdoc.swagger-ui.enabled=true

在实体类中添加注解

此处以User实体类为例，其他的实体类参考User实体类根据需要添加即可。

@Schema(description = "用户实体类")
public class User extends BaseEntity implements Serializable {
    @Schema(description = "用户id")
    private Integer Uid;
    @Schema(description = "用户名")
    private String username;
    @Schema(description = "用户密码")
    private String password;
    @Schema(description = "盐值")
    private String salt;
    @Schema(description = "手机号码")
    private String phone;
    @Schema(description = "电子邮件")
    private String email;
    @Schema(description = "用户id")
    private Integer gender;
    @Schema(description = "用户头像")
    private String avatar;
    @Schema(description = "是否删除")
    private Integer isDelete;

    // ...
}

在控制类中添加注解

此处以UserController控制类为例，其他控制类根据需要添加即可。

@Tag(name = "用户接口", description = "用于用户注册、登录、修改信息、修改头像等")
//@Controller
@RestController // @Controller + @ResponseBody
@RequestMapping("users")
public class UserController extends BaseController{
    @Autowired
    private IUserService userService;

    /**
     * 约定大于配置：开发思想来完成，省略了大量的配置甚至注解的编写
     * 1 接收数据方式：请求处理方法的参数列表设置为pojo类型来接收前端的数据
     * SpringBoot会将前端的url地址中的参数名和pojo类的属性名进行比较，如果这两个名称相等，则将值注入到pojo类中对应的属性上
     */
    @Operation(summary = "注册用户", description = "用户注册")
    @PostMapping("reg")
    //@ResponseBody // 表示此方法的响应以json格式进行数据的响应给到前端，不建议这么写
    public JsonResult<Void> reg(@Parameter(description = "用户对象", required = true) User user) {
        userService.reg(user);

        return new JsonResult<>(OK);
    }
}

创建SpringDoc配置类

在config下创建SpringDocConfig类：

@Configuration
public class SpringDocConfig {

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("Store API")
                        .description("Store API")
                        .version("v0.0.1")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("Store Documentation")
                        .url(""));
    }
}

这里有两个，常用的是api，admin下的是一些隐藏接口，这个根据需要添加。