Java 后端研发中的文档工程化实践：从代码注解到 API 契约驱动

package com.example.demo.api;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;

@Tag(name = "Order Command & Query", description = "订单生命周期管理接口")
public interface OrderApi {

    @Operation(summary = "查询订单详情", description = "根据订单唯一标识获取订单基础状态及支付明细")
    @ApiResponse(responseCode = "200", description = "查询成功")
    @ApiResponse(responseCode = "404", description = "订单未找到")
    @GetMapping("/api/v1/orders/{orderId}")
    ResponseEntity<OrderDTO> getOrderById(
            @Parameter(description = "订单主键 ID", required = true, example = "10248892")
            @PathVariable("orderId") Long orderId
    );
}

@RestController
public class OrderController implements OrderApi {

    private final OrderQueryService orderQueryService;

    public OrderController(OrderQueryService orderQueryService) {
        this.orderQueryService = orderQueryService;
    }

    @Override
    public ResponseEntity<OrderDTO> getOrderById(Long orderId) {
        return ResponseEntity.ok(orderQueryService.findById(orderId));
    }
}

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

workspace "Order System" "系统架构全景" {

    model {
        user = person "消费者" "在移动端或 Web 发起下单请求"
        
        enterprise "零售系统" {
            orderSystem = softwareSystem "订单核心系统" "管理订单状态流转与持久化" {
                webApp = container "Web 前端" "提供用户交互界面" "React"
                apiGateway = container "API Gateway" "流量路由、限流与鉴权" "Spring Cloud Gateway"
                orderService = container "Order Service" "核心业务处理" "Spring Boot 3.2"
                orderDb = container "Order Database" "订单关系数据存储" "PostgreSQL 16"
            }
            paymentSystem = softwareSystem "第三方支付网关" "微信/支付宝清算通道" "External"
        }

        user -> webApp "操作浏览"
        webApp -> apiGateway "发起 HTTPS 调用"
        apiGateway -> orderService "gRPC / REST 转发"
        orderService -> orderDb "JDBC 读写"
        orderService -> paymentSystem "发起扣款请求"
    }

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

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>2.2.6</version>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-diagram</artifactId>
            <version>2.3.0</version>
        </dependency>
    </dependencies>
    <configuration>
        <sourceDirectory>src/docs/asciidoc</sourceDirectory>
        <outputDirectory>${project.build.directory}/generated-docs</outputDirectory>
        <attributes>
            <toc>left</toc>
            <icons>font</icons>
            <sectanchors>true</sectanchors>
        </attributes>
        <requires>
            <require>asciidoctor-diagram</require>
        </requires>
    </configuration>
</plugin>

= 订单核心系统后端架构手册
v1.0.0, 2024-03-20
:doctype: book

== 1. 架构总览
[plantuml, format="svg"]
....
include::../architecture/system-context.puml[]
....

== 2. 核心状态机设计
include::state-machine.adoc[]

== 3. API 契约定义
include::api-guide.adoc[]