OpenAPI/Swagger API Practical Guide dengan Claude Code

OpenAPI/Swaggerdefinisi dengan Claude Code: efisiensi

API設計ファースト アプローチ 、implementasi前 OpenAPI仕様 definisi.Claude Code 使えば、包括的なAPI仕様書 pembuatan dari clientコードgenerateま 一気 進められ.

pembuatan OpenAPI仕様

RESTful APIのdefinisi

> ブログAPI OpenAPI 3.1仕様 buatkan.
> artikel CRUD、タグmanajemen、認証 含めて。

openapi: 3.1.0
info:
  title: Blog API
  version: 1.0.0
  description: ブログ管理用REST API

servers:
  - url: https://api.example.com/v1
    description: 本番環境

paths:
  /posts:
    get:
      summary: 記事一覧の取得
      operationId: listPosts
      tags: [posts]
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: tag
          in: query
          schema:
            type: string
          description: タグでフィルター
      responses:
        '200':
          description: 記事一覧
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Post'
                  meta:
                    $ref: '#/components/schemas/Pagination'
    post:
      summary: 記事の作成
      operationId: createPost
      tags: [posts]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePostRequest'
      responses:
        '201':
          description: 作成成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  schemas:
    Post:
      type: object
      required: [id, title, content, createdAt]
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
          maxLength: 200
        content:
          type: string
        tags:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    CreatePostRequest:
      type: object
      required: [title, content]
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        content:
          type: string
          minLength: 1
        tags:
          type: array
          items:
            type: string

    Pagination:
      type: object
      properties:
        currentPage:
          type: integer
        totalPages:
          type: integer
        totalItems:
          type: integer

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

コードgenerate

TypeScript型とclientの自動generate

> OpenAPIdefinisi dari TypeScript 型definisi dan APIclient generate.
> openapi-typescript 使って。

// generateされた型 使ったAPIclient
import type { paths } from './generated/api';
import createClient from 'openapi-fetch';

const client = createClient<paths>({
  baseUrl: 'https://api.example.com/v1',
});

// type safetyなAPI呼び出し
const { data, error } = await client.GET('/posts', {
  params: {
    query: { page: 1, limit: 10, tag: 'typescript' },
  },
});

validasiintegrasi

OpenAPIdefinisi runtimevalidasi pemanfaatan こ dan 、仕様 dan implementasi 乖離 防げ.

> OpenAPIdefinisi dari Zodスキーマ generate.
> request・response 両方 validasiして。

mockserver

OpenAPIdefinisi dari mockserver 立ち上げ、frontendpengembangan 並行 進められ.Claude Code 「Prism mockserver 起動 pengaturan 作って」 dan 依頼すれば、即座 pemanfaatandimungkinkan.

Summary

Dengan Claude Code, OpenAPI仕様 pembuatan dari コードgenerate、validasiintegrasiま 一貫 APIpengembanganworkflow pembangunan bisa dilakukan.APIpengembanganpanduanやAPItestotomatisasi juga 合わせて参考 .

Untuk OpenAPIの詳細, lihat OpenAPI InitiativeおよびSwagger公式ドキュメント.