2024年1月Java项目开发指南17：自动接口文档配置

Knife4j 文档 ：https://doc.xiaominfo.com/

有能力的建议自己去看文档配置，本文仅做参考，因为官方文档会更新，本文不会，以后说不定本文就过时了。

ok，我们继续。虽然本文是2024年1月Java项目开发指南17，但实际上与前面的并没有什么关联（不是基于之前的项目的），这一点需要你知道。

导入依赖：

		<dependency>
			<groupId>com.github.xiaoymin</groupId>
			<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
			<version>4.5.0</version>
		</dependency>

配置(properties)：

注意等号后面没有空格内容也没有使用任何引号引起来

# springdoc-openapi
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.swagger-ui.tags-sorter=alpha
springdoc.swagger-ui.operations-sorter=alpha
springdoc.api-docs.path=/v3/api-docs
springdoc.group-configs[0].group=default
springdoc.group-configs[0].paths-to-match=/**
springdoc.group-configs[0].packages-to-scan=com.guaiguailang.harmony.controller

注意：packages-to-scan 的值 要改成符合自己的项目，不要照抄

如果你配置文件不是这种格式，另外一种格式(yml)如下：

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.xiaominfo.knife4j.demo.web
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

注意：packages-to-scan 的值 要改成符合自己的项目结构信息

就这样就可以了，还可以搞点有意思的，就是运行的时候输出文档地址，效果就像这样：

那么怎么做呢，首先配置文件要有：

# Server Info Setting
server.port=8080
server.servlet.context-path=/
server.servlet.session.timeout=3600

然后在启动文件里面写：

package com.guaiguailang.harmony;

import com.github.yitter.contract.IIdGenerator;
import com.github.yitter.contract.IdGeneratorOptions;
import com.github.yitter.idgen.YitIdHelper;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ConfigurableApplicationContext;

@SpringBootApplication
public class HarmonyLifeServerApplication {

	public static void main(String[] args) {
//		SpringApplication.run(HarmonyLifeServerApplication.class, args);
		// 启动 Spring Boot 应用
		ConfigurableApplicationContext context = SpringApplication.run(HarmonyLifeServerApplication.class, args);

		// 获取服务器端口
		int port = context.getEnvironment().getProperty("server.port", Integer.class);
		// 获取服务器上下文路径，默认为"/"
		String contextPath = context.getEnvironment().getProperty("server.servlet.context-path", "/");
		if (contextPath.equals("/")) {
			contextPath = "";
		}
		System.out.println("^_^ 青山埋忠骨，烟巷葬伟杰        ORZ···");
		System.out.println("工    作    区  ："+work_space+" (请保证工作区全局唯一)");
		// 输出项目访问地址
		System.out.println("访   问  地  址 : http://localhost:" + port + contextPath);

		// 输出 Swagger 文档地址
		System.out.println("Swagger 文档地址: http://localhost:" + port + contextPath + "/swagger-ui.html");
		System.out.println("Knife4j 文档地址: http://localhost:" + port + contextPath + "/doc.html");
		System.out.println("^_^ 仙之巅 傲世间 先有萌狼后有天    ORZ···");
	}

}

完毕

package com.guaiguailang.harmony.controller;

import com.guaiguailang.harmony.domain.dto.ParamLogin;
import com.guaiguailang.harmony.domain.vo.ResponseResult;
import com.guaiguailang.harmony.service.AuthService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@Tag(name="系统认证接口")
@RequestMapping("/auth")
public class AuthController {
    @Autowired
    private final AuthService authService;
    // （为什么加个final？）使用构造器注入 AuthService，这在 Spring Boot 中是推荐的做法。
    /*
    使用构造器注入（Constructor Injection）在 Spring Boot 中是一种推荐的做法，主要有以下几个原因和好处：
    1. 强制依赖
    构造器注入确保了依赖项在对象创建时就必须存在，这意味着任何依赖项都必须在构造对象时就提供。这种方式可以避免运行时的 NullPointerException（空指针异常），因为依赖项在对象创建时就已经被初始化。
    2. 不可变性
    构造器注入有助于创建不可变对象（Immutable Objects）。一旦对象通过构造器接收了其所需的依赖项，这些依赖项就不能被改变。这有助于提高代码的可预测性和安全性。
    3. 清晰性
    构造器注入使得依赖关系非常明确。当查看类的构造器时，可以立即看到该类依赖哪些组件，这提高了代码的可读性和可维护性。
    4. 测试友好
    构造器注入使得单元测试变得更容易。可以通过构造器直接传入模拟对象（Mock Objects），而不需要依赖框架提供的 setter 方法或其他注入方式。这使得测试代码更加简洁明了。
    5. 减少副作用
    构造器注入减少了类内部的副作用。与使用 setter 注入相比，构造器注入避免了在对象创建之后通过 setter 方法来修改其状态的情况，从而减少了潜在的副作用。
    6. 生命周期管理
    构造器注入有助于 Spring 容器更好地管理 bean 的生命周期。依赖项在构造器中声明后，Spring 容器可以在创建 bean 时就注入这些依赖项，从而确保 bean 在使用前就已经处于完全初始化的状态。
     */
    // 哥们，你在这做面试题呢？不，我只是开发过程中记录一下，这些是我逝去的青春。
    public AuthController(AuthService authService) {
        this.authService = authService;
    }

    @Operation(
            summary = "用户登录 账号登录",
            description = "用户通过账号密码进行登录",
            tags = {"系统认证接口"},
            requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(
                    content = @Content(mediaType = "application/json", schema = @Schema(implementation = ParamLogin.class))
            ),
            responses = {
                    @ApiResponse(
                            responseCode = "200",
                            description = "成功返回登录结果",
                            content = @Content(
                                    mediaType = "application/json",
                                    schema = @Schema(
                                            implementation = ResponseResult.class,
                                            example = "{ \"msg\": \"登录成功\", \"data\": {\"token\":\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\", \"userId\":1}, \"code\":200 }"
                                    )
                            )
                    ),
                    @ApiResponse(responseCode = "400", description = "请求参数错误"),
                    @ApiResponse(responseCode = "401", description = "未授权"),
                    @ApiResponse(responseCode = "500", description = "内部服务器错误")
            }
    )
    @PostMapping("/login")
    public ResponseEntity loginByAccount(@RequestBody ParamLogin loginParam){
        return ResponseEntity.ok(authService.loginByAccount(loginParam));
    }
}