Add OpenAPI templates for medium and large scale projects

openapi_templates/README.md

@@ -0,0 +1,69 @@
+# OpenAPI Templates
+
+このディレクトリには、中規模および大規模プロジェクト向けのOpenAPI定義ファイルのテンプレートが含まれています。プロジェクトの規模やチーム構成に合わせて選択してください。
+
+## 1. 中規模プロジェクト向け (`medium/`)
+
+**特徴:**
+- 機能ごとにファイルを分割しますが、ディレクトリ階層は浅く保ちます。
+- `paths/` と `components/` にファイルを分けることで、単一ファイル `openapi.yaml` が肥大化するのを防ぎます。
+- 比較的小規模なチームや、ドメインが複雑に入り組んでいない場合に適しています。
+
+**構成:**
+```
+medium/
+├── openapi.yaml          # エントリーポイント
+├── paths/                # パス定義 (例: users.yaml)
+└── components/
+    ├── schemas/          # スキーマ定義 (例: User.yaml)
+    ├── parameters/       # パラメータ定義
+    └── responses/        # レスポンス定義
+```
+
+## 2. 大規模プロジェクト向け (`large/`)
+
+**特徴:**
+- **ドメイン駆動設計 (DDD)** を意識し、機能領域 (Domain) ごとにディレクトリを分割します。
+- 各ドメイン (`domains/users` 等) が独立して開発できるように設計されています。
+- 共通のスキーマやパラメータは `shared/` ディレクトリで管理します。
+- 複数のチームが並行して開発する場合や、マイクロサービスアーキテクチャを採用している場合に適しています。
+
+**構成:**
+```
+large/
+├── openapi.yaml          # 全体のエントリーポイント (各ドメインを参照)
+├── domains/              # ドメインごとの定義
+│   └── users/
+│       ├── index.yaml    # ドメインのエントリーポイント
+│       ├── paths/        # ドメイン固有のパス
+│       └── schemas/      # ドメイン固有のスキーマ
+└── shared/               # 共有リソース
+    ├── schemas/          # 共通スキーマ (例: Error)
+    └── parameters/       # 共通パラメータ (例: Pagination)
+```
+
+## ツールの利用方法
+
+これらのテンプレートは複数のファイルに分割されているため、ツールを使用して単一のファイルにバンドル (結合) することをお勧めします。
+
+### 推奨ツール
+
+1. **swagger-cli**
+   ```bash
+   npm install -g @apidevtools/swagger-cli
+   swagger-cli bundle openapi_templates/medium/openapi.yaml -o dist/openapi.json -t json
+   ```
+
+2. **Redocly CLI**
+   ```bash
+   npm install -g @redocly/cli
+   redocly bundle openapi_templates/large/openapi.yaml -o dist/openapi.yaml
+   ```
+
+### 検証 (Validation)
+
+作成したファイルが正しいOpenAPI仕様に準拠しているか確認するには、以下のようにコマンドを実行します。
+
+```bash
+swagger-cli validate openapi_templates/medium/openapi.yaml
+```

openapi_templates/large/domains/users/index.yaml

@@ -0,0 +1,36 @@
+openapi: 3.0.3
+info:
+  title: Users Domain
+  version: 1.0.0
+  description: Operations related to users.
+
+paths:
+  /users:
+    get:
+      summary: List all users
+      tags:
+        - Users
+      parameters:
+        - $ref: '../../shared/parameters/Pagination.yaml'
+      responses:
+        '200':
+          description: A list of users
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: './schemas/User.yaml'
+        '500':
+          description: Internal Server Error
+          content:
+            application/json:
+              schema:
+                $ref: '../../shared/schemas/Error.yaml'
+  /users/{userId}:
+    $ref: './paths/get_user.yaml'
+
+components:
+  schemas:
+    User:
+      $ref: './schemas/User.yaml'

openapi_templates/large/domains/users/paths/get_user.yaml

@@ -0,0 +1,25 @@
+get:
+  summary: Get a user by ID
+  tags:
+    - Users
+  parameters:
+    - name: userId
+      in: path
+      required: true
+      schema:
+        type: string
+        format: uuid
+      description: The ID of the user to retrieve
+  responses:
+    '200':
+      description: User details
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/User.yaml'
+    '404':
+      description: User not found
+      content:
+        application/json:
+          schema:
+            $ref: '../../../shared/schemas/Error.yaml'

openapi_templates/large/domains/users/schemas/User.yaml

@@ -0,0 +1,16 @@
+type: object
+required:
+  - id
+  - username
+properties:
+  id:
+    type: string
+    format: uuid
+    example: "123e4567-e89b-12d3-a456-426614174000"
+  username:
+    type: string
+    example: "johndoe"
+  email:
+    type: string
+    format: email
+    example: "john.doe@example.com"

openapi_templates/large/openapi.yaml

@@ -0,0 +1,25 @@
+openapi: 3.0.3
+info:
+  title: Large Scale Project API
+  version: 1.0.0
+  description: API template for large-scale projects. Uses Domain-Driven Design (DDD) structure.
+
+servers:
+  - url: http://localhost:8080/api/v1
+    description: Local Development Server
+
+paths:
+  # Paths are aggregated from domains
+  /users:
+    $ref: './domains/users/index.yaml#/paths/~1users'
+  /users/{userId}:
+    $ref: './domains/users/index.yaml#/paths/~1users~1{userId}'
+
+components:
+  schemas:
+    # Shared schemas can be referenced directly or via domain files
+    Error:
+      $ref: './shared/schemas/Error.yaml'
+  parameters:
+    PaginationLimit:
+      $ref: './shared/parameters/Pagination.yaml'

openapi_templates/large/shared/parameters/Pagination.yaml

@@ -0,0 +1,9 @@
+name: limit
+in: query
+description: Maximum number of items to return
+required: false
+schema:
+  type: integer
+  default: 10
+  minimum: 1
+  maximum: 100

openapi_templates/large/shared/schemas/Error.yaml

@@ -0,0 +1,12 @@
+type: object
+required:
+  - code
+  - message
+properties:
+  code:
+    type: integer
+    format: int32
+    example: 404
+  message:
+    type: string
+    example: "Resource not found"

openapi_templates/medium/components/schemas/User.yaml

@@ -0,0 +1,14 @@
+type: object
+required:
+  - id
+  - username
+properties:
+  id:
+    $ref: './UserId.yaml'
+  username:
+    type: string
+    example: "johndoe"
+  email:
+    type: string
+    format: email
+    example: "john.doe@example.com"

openapi_templates/medium/components/schemas/UserId.yaml

@@ -0,0 +1,3 @@
+type: string
+format: uuid
+example: "123e4567-e89b-12d3-a456-426614174000"

openapi_templates/medium/openapi.yaml

@@ -0,0 +1,20 @@
+openapi: 3.0.3
+info:
+  title: Medium Scale Project API
+  version: 1.0.0
+  description: API template for medium-scale projects. Uses file splitting for paths and components.
+
+servers:
+  - url: http://localhost:8080/api/v1
+    description: Local Development Server
+
+paths:
+  /users:
+    $ref: './paths/users.yaml'
+
+components:
+  schemas:
+    User:
+      $ref: './components/schemas/User.yaml'
+    UserId:
+      $ref: './components/schemas/UserId.yaml'

openapi_templates/medium/paths/users.yaml

@@ -0,0 +1,33 @@
+get:
+  summary: List all users
+  tags:
+    - Users
+  responses:
+    '200':
+      description: A list of users
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: '../components/schemas/User.yaml'
+    '500':
+      description: Internal Server Error
+
+post:
+  summary: Create a new user
+  tags:
+    - Users
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '../components/schemas/User.yaml'
+  responses:
+    '201':
+      description: User created
+      content:
+        application/json:
+          schema:
+            $ref: '../components/schemas/User.yaml'