doc: separate openapi.yaml

adapter/gateway/mysql/transaction.go

@@ -2,6 +2,7 @@ package mysql
 
 import (
 	"context"
+
 	"go-gin-clean-arch/config"
 	"go-gin-clean-arch/domain"
 	"gorm.io/gorm"

compose.yaml

@@ -34,5 +34,7 @@ services:
       - "8081:8080"
     volumes:
       - ./doc/openapi.yaml:/openapi.yaml
+      - ./doc/paths:/paths
+      - ./doc/components:/components
     environment:
-      SWAGGER_JSON: /openapi.yaml
+      SWAGGER_JSON: /openapi.yaml

doc/components/examples/users.yaml

@@ -0,0 +1,26 @@
+create_request:
+  value:
+    email: 'example@example.com'
+    password: 'password'
+    password_confirm: 'password'
+
+login_request:
+  value:
+    session: false
+    email: 'example@example.com'
+    password: 'password'
+
+refresh_token_request:
+  value:
+    session: false
+    refresh_token: ''
+
+reset_password_request_request:
+  value:
+    email: 'example@example.com'
+
+reset_password_request:
+  value:
+    recovery_token: ''
+    password: 'password'
+    password_confirm: 'password'

doc/components/schemas/users.yaml

@@ -0,0 +1,69 @@
+create_request:
+  type: object
+  properties:
+    email:
+      type: string
+      format: email
+    password:
+      type: string
+    password_confirm:
+      type: string
+
+login_request:
+  type: object
+  properties:
+    session:
+      type: boolean
+      description: If true, the response will contain a session token
+    email:
+      type: string
+    password:
+      type: string
+
+login_response:
+  type: object
+  properties:
+    token:
+      type: string
+    refresh_token:
+      type: string
+
+refresh_token_request:
+  type: object
+  properties:
+    session:
+      type: boolean
+    refresh_token:
+      type: string
+
+refresh_token_response:
+  type: object
+  properties:
+    token:
+      type: string
+    refresh_token:
+      type: string
+
+reset_password_request_request:
+  type: object
+  properties:
+    email:
+    type: string
+
+reset_password_request:
+  type: object
+  properties:
+    recovery_token:
+      type: string
+    password:
+      type: string
+    password_confirm:
+      type: string
+
+me_response:
+  type: object
+  properties:
+    id:
+      type: string
+    email:
+      type: string

doc/openapi.yaml

@@ -1,137 +1,42 @@
 openapi: 3.1.0
 
 info:
-  title: Go DDD
+  title: Go API
   version: 1.0.0
 
 servers:
   - url: http://localhost:8080
+    description: Local server
 
 tags:
+  - name: Health
+    description: ヘルスチェック
   - name: User
+    description: ユーザー
 
 paths:
-  /users:
-    post:
+  /health:
+    get:
       tags:
-        - User
-      summary: Create
-      requestBody:
-        content:
-          application/json:
-            schema:
-              type: object
-              example:
-                email: 'example@example.com'
-                password: 'password'
-                password_confirm: 'password'
+        - Health
+      summary: Health
       responses:
         '200':
           description: Successful response
           content:
             application/json: { }
+  /users:
+    $ref: './paths/users.yaml#/users'
   /users/login:
-    post:
-      tags:
-        - User
-      summary: Login
-      requestBody:
-        content:
-          application/json:
-            schema:
-              type: object
-              example:
-                session: false
-                email: 'example@example.com'
-                password: 'password'
-      responses:
-        '200':
-          description: Successful response
-          content:
-            application/json: { }
+    $ref: './paths/users.yaml#/login'
   /users/refresh-token:
-    post:
-      security:
-        - bearerAuth: [ ]
-      tags:
-        - User
-      summary: RefreshToken
-      requestBody:
-        content:
-          application/json:
-            schema:
-              type: object
-              example:
-                session: false
-                refresh_token: ''
-      responses:
-        '200':
-          description: Successful response
-          content:
-            application/json: { }
+    $ref: './paths/users.yaml#/refresh_token'
   /users/reset-password-request:
-    patch:
-      security:
-        - bearerAuth: [ ]
-      tags:
-        - User
-      summary: ResetPasswordRequest
-      requestBody:
-        content:
-          application/json:
-            schema:
-              type: object
-              example:
-                email: 'example@example.com'
-      responses:
-        '200':
-          description: Successful response
-          content:
-            application/json: { }
+    $ref: './paths/users.yaml#/reset_password_request'
   /users/reset-password:
-    patch:
-      security:
-        - bearerAuth: [ ]
-      tags:
-        - User
-      summary: ResetPassword
-      requestBody:
-        content:
-          application/json:
-            schema:
-              type: object
-              example:
-                recovery_token: ''
-                password: 'password'
-                password_confirm: 'password'
-      responses:
-        '200':
-          description: Successful response
-          content:
-            application/json: { }
+    $ref: './paths/users.yaml#/reset_password'
   /users/me:
-    get:
-      security:
-        - bearerAuth: [ ]
-      tags:
-        - User
-      summary: Me
-      responses:
-        '200':
-          description: Successful response
-          content:
-            application/json: { }
-  /health:
-    get:
-      tags:
-        - default
-      summary: Health
-      responses:
-        '200':
-          description: Successful response
-          content:
-            application/json: { }
-
+    $ref: './paths/users.yaml#/me'
 
 components:
   securitySchemes:

doc/paths/users.yaml

@@ -0,0 +1,113 @@
+users:
+  post:
+    tags:
+      - User
+    summary: Create
+    requestBody:
+      content:
+        application/json:
+          schema:
+            $ref: '../components/schemas/users.yaml#/create_request'
+          examples:
+            ok:
+              $ref: '../components/examples/users.yaml#/create_request'
+    responses:
+      '200':
+        description: Successful response
+
+login:
+  post:
+    tags:
+      - User
+    summary: Login
+    requestBody:
+      content:
+        application/json:
+          schema:
+            $ref: '../components/schemas/users.yaml#/login_request'
+          examples:
+            ok:
+              $ref: '../components/examples/users.yaml#/login_request'
+    responses:
+      '200':
+        description: Successful response
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas/users.yaml#/login_response'
+
+refresh_token:
+  post:
+    security:
+      - bearerAuth: [ ]
+    tags:
+      - User
+    summary: RefreshToken
+    requestBody:
+      content:
+        application/json:
+          schema:
+            $ref: '../components/schemas/users.yaml#/refresh_token_request'
+          examples:
+            ok:
+              $ref: '../components/examples/users.yaml#/refresh_token_request'
+    responses:
+      '200':
+        description: Successful response
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas/users.yaml#/refresh_token_response'
+
+reset_password_request:
+  patch:
+    security:
+      - bearerAuth: [ ]
+    tags:
+      - User
+    summary: ResetPasswordRequest
+    requestBody:
+      content:
+        application/json:
+          schema:
+            $ref: '../components/schemas/users.yaml#/reset_password_request'
+          examples:
+            ok:
+              $ref: '../components/examples/users.yaml#/reset_password_request'
+    responses:
+      '200':
+        description: Successful response
+
+reset_password:
+  patch:
+    security:
+      - bearerAuth: [ ]
+    tags:
+      - User
+    summary: ResetPassword
+    requestBody:
+      content:
+        application/json:
+          schema:
+            $ref: '../components/schemas/users.yaml#/reset_password_request'
+          examples:
+            ok:
+              $ref: '../components/examples/users.yaml#/reset_password_request'
+    responses:
+      '200':
+        description: Successful response
+
+me:
+  get:
+    security:
+      - bearerAuth: [ ]
+    tags:
+      - User
+    summary: Me
+    responses:
+      '200':
+        description: Successful response
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas/users.yaml#/me_response'