SpringBoot项目集成Smart-Doc的实战指南

import com.toher.springdoc.bean.User;
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.responses.ApiResponses;
import org.springframework.web.bind.annotation.*;

/**
 * @Author 麦可乐
 * @Date 2025/10/20 11:17 AM
 * @Version 1.0
 */

@RestController
@RequestMapping("/api/users")
public class UserController {

    @Operation(summary = "获取用户信息接口", description = "通过用户ID获取用户信息")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "用户信息",
                    content = {@Content(mediaType = "application/json",
                    schema = @Schema(implementation = User.class))}),
            @ApiResponse(responseCode = "404", description = "无法获取用户信息")
    })
    @GetMapping("/{id}")
    public User getUserById(@Parameter(description = "用户ID") @PathVariable Long id) {
        //模拟数据库获取用户
        User user = new User();
        user.setId(1L);
        user.setName("张三");
        user.setEmail("zhansan@qq.com");
        return user;
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.5.7</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.toher</groupId>
    <artifactId>smart-doc-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>smart-doc-demo</name>
    <description>smart-doc-demo</description>

    <properties>
        <java.version>17</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>

            <plugin>
                <groupId>com.ly.smart-doc</groupId>
                <artifactId>smart-doc-maven-plugin</artifactId>
                <version>3.1.1</version>
                <configuration>
                    <configFile>./src/main/resources/smart-doc.json</configFile>
                    <projectName>${project.description}</projectName>
                </configuration>
                <executions>
                    <execution>
                        <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
                        <phase>compile</phase>
                        <goals>
                            <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
                            <goal>html</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

{
  "outPath": "src/main/resources/static/doc",
  "projectName": "SmartDoc Demo",
  "allInOne": true,
  "serverUrl": "http://localhost:8080",
  "packageFilters": "com.toher.smartdocdemo.controller",
  "sourceCodePaths": [
    {
      "path": "src/main/java",
      "desc": "Main Source"
    }
  ]
}

/**
 * 用户实体类
 *
 * @Author: micro麦可乐
 * @Date: 2025/10/20 18:59
 *
 **/
@Data
@AllArgsConstructor
public class User {
    /**
     * 用户ID主键
     */
    private Long id;
    /**
     * 用户名称
     */
    private String name;
}

/**
 * 用户管理接口
 * @Author: micro麦可乐
 * @Date: 2025/10/20 18:59
 */
@RestController
@RequestMapping("/users")
public class UserController {

    /**
     * 获取用户列表
     * @return 返回用户列表
     */
    @GetMapping
    public List<User> list() {
        List<User> list = new ArrayList<>();
        list.add(new User(1L, "Alice"));
        list.add(new User(2L, "Bob"));
        return list;
    }

    /**
     * 创建用户
     * @param user
     * @return 返回创建用户
     */
    @PostMapping
    public User create(@RequestBody User user) {
        user.setId(3L);
        return user;
    }

    /**
     * 根据ID获取用户信息
     * @param id 用户ID
     * @return 返回用户对象
     */
    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        return new User(id, "张三");
    }
}

mvn smart-doc:html