mcpField
O
openapi-first

openapi-first

github.com/rrezartprebreza开发32897 次安装6 天前更新
代码仓库

关于 openapi-first

面向 Java 和 Spring 团队的开发技能，用于基于 OpenAPI 规范构建 API，涵盖代码生成、委托实现及生成器配置易错点。

主要功能

  1. 01OpenAPI Generator Maven 配置
  2. 02API 规范结构
  3. 03基于委托的实现
  4. 04生成源码管理
  5. 05生成器配置指引

适用场景

  1. 01从 OpenAPI 文件生成 Spring API 代码
  2. 02不修改生成的控制器而实现操作
  3. 03避免将生成源码纳入版本控制
  4. 04检查 Spring Boot 3 生成器设置

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/rrezartprebreza/spring-boot-skills --skill openapi-first

安装后在 Claude Code 中输入/openapi-first确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
examples/
bad-delegate-impl.java
good-delegate-impl.java
templates/
openapi.yaml

详细介绍

OpenAPI 优先开发

Maven 插件设置

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>7.5.0</version>
    <executions>
        <execution>
            <goals><goal>generate</goal></goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
                <generatorName>spring</generatorName>
                <apiPackage>com.example.api</apiPackage>
                <modelPackage>com.example.api.model</modelPackage>
                <configOptions>
                    <delegatePattern>true</delegatePattern>      
                    <interfaceOnly>false</interfaceOnly>
                    <useSpringBoot3>true</useSpringBoot3>
                    <useTags>true</useTags>
                    <dateLibrary>java8</dateLibrary>
                    <openApiNullable>false</openApiNullable>
                    <skipDefaultInterface>false</skipDefaultInterface> 
                </configOptions>
                
                <supportingFilesToGenerate>ApiUtil.java</supportingFilesToGenerate>
                <modelNameSuffix>Dto</modelNameSuffix> 
                <output>${project.build.directory}/generated-sources/openapi</output>
            </configuration>
        </execution>
    </executions>
</plugin>

OpenAPI 规范示例

# src/main/resources/openapi.yaml
openapi: 3.0.3
info:
  title: Order Service API
  version: 1.0.0

paths:
  /api/v1/orders:
    post:
      tags: [Orders]
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          $ref: '#/components/responses/ValidationError'

    get:
      tags: [Orders]
      operationId: listOrders
      parameters:
        - name: page
          in: query
          schema: { type: integer, default: 0 }
        - name: size
          in: query
          schema: { type: integer, default: 20 }
      responses:
        '200':
          description: Paginated orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderPage'

components:
  schemas:
    CreateOrderRequest:
      type: object
      required: [customerEmail, items]
      properties:
        customerEmail:
          type: string
          format: email
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/OrderItemRequest'

    OrderResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum: [PENDING, PROCESSING, SHIPPED, DELIVERED, CANCELLED]
        customerEmail:
          type: string
        createdAt:
          type: string
          format: date-time

    OrderItemRequest:
      type: object
      required: [productId, quantity]
      properties:
        productId:
          type: string
          format: uuid
        quantity:
          type: integer
          minimum: 1

    OrderPage:
      type: object
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/OrderResponse'
        page:
          type: integer
        size:
          type: integer
        totalElements:
          type: integer
          format: int64

    ApiError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: string

  responses:
    ValidationError:
      description: Validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'

实现委托

// Generated: OrdersApi interface with delegate
// Your implementation — never modify generated files

@Service
@RequiredArgsConstructor
public class OrdersApiDelegateImpl implements OrdersApiDelegate {

    private final OrderService orderService;

    @Override
    public ResponseEntity<OrderResponse> createOrder(CreateOrderRequest request) {
        Order order = orderService.createOrder(request);
        return ResponseEntity.status(HttpStatus.CREATED)
            .body(OrderApiMapper.toResponse(order));
    }

    @Override
    public ResponseEntity<OrderPage> listOrders(Integer page, Integer size) {
        Page<Order> orders = orderService.findAll(PageRequest.of(page, size));
        return ResponseEntity.ok(OrderApiMapper.toPage(orders));
    }
}

.gitignore — 切勿提交生成的文件

target/generated-sources/openapi/

注意事项

  • Agent 修改生成的控制器文件——切勿修改生成的代码，应实现委托
  • Agent 生成代码时未设置 useSpringBoot3=true——会使用旧版 javax.* 导入
  • Agent 提交生成的源代码——将其添加到 .gitignore，并在构建时生成
  • Agent 将 skipDefaultInterface=true 与 delegatePattern=true 一起设置——生成的控制器会实例化一个空操作委托，导致无法继续编译；请保持为 false，并为每个操作编写契约测试
  • Agent 设置 generateSupportingFiles=true——会生成第二个 @SpringBootApplication 和 SpringDoc 配置；在 supportingFilesToGenerate 中仅列出 ApiUtil.java
  • Agent 混用生成的模型和手写模型——请将它们分开

评论

支持 Markdown