基于 Spring Boot 3 与 OpenAPI 3 的后端架构文档工程化实践

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

package com.example.demo.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Core Platform API")
                        .version("v1.2.0")
                        .description("订单与支付核心域契约文档")
                        .license(new License().name("Apache 2.0")));
    }
}

@ExtendWith(RestDocumentationExtension.class)
@SpringBootTest
public class OrderDocumentationTest {

    private MockMvc mockMvc;

    @BeforeEach
    public void setUp(WebApplicationContext webApplicationContext,
                      RestDocumentationContextProvider restDocumentation) {
        this.mockMvc = MockMvcBuilders.webAppContextSetup(webApplicationContext)
                .apply(documentationConfiguration(restDocumentation))
                .build();
    }

    @Test
    public void should_generate_order_create_doc() throws Exception {
        this.mockMvc.perform(post("/orders")
                .contentType(MediaType.APPLICATION_JSON)
                .content("{\"itemId\": 1001, \"amount\": 2}"))
                .andExpect(status().isCreated())
                .andDo(document("order-create",
                        requestFields(
                                fieldWithPath("itemId").description("商品唯一标识 ID"),
                                fieldWithPath("amount").description("购买数量")
                        )));
    }
}

workspace "OrderSystem" "订单系统架构" {

    model {
        user = person "C端用户" "浏览商品并下单"
        
        orderSystem = softwareSystem "订单核心系统" {
            webApp = container "Web SPA" "用户前端操作界面" "Vue 3"
            backendService = container "Order Service" "处理核心订单状态机" "Spring Boot 3.x / Java 21"
            orderDb = container "Order Database" "存储订单事务数据" "PostgreSQL 16"
        }

        user -> webApp "操作下单"
        webApp -> backendService "REST/JSON 调用"
        backendService -> orderDb "JDBC 读写"
    }

    views {
        container orderSystem "Containers" {
            include *
            autolayout lr
        }
        theme default
    }
}

<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>1.4</version>
    <executions>
        <execution>
            <id>integration-test</id>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
        <outputFileName>openapi.json</outputFileName>
        <outputDir>${project.build.directory}/contract</outputDir>
    </configuration>
</plugin>