From 889cf7bbd02c8be2d248d13d234d55abd5ee6bc8 Mon Sep 17 00:00:00 2001
From: ma91n <mano.junki@gmail.com>
Date: Fri, 1 Dec 2023 10:37:56 +0900
Subject: [PATCH] component/response

---
 .../OpenAPI_Specification_3.0.3.md            | 73 +++++++++++++++++--
 1 file changed, 66 insertions(+), 7 deletions(-)

diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md
index de977cca..50274cbc 100644
--- a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md
+++ b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md
@@ -319,7 +319,7 @@ components:
         ...
 ```
 
-​### responses
+### responses
 
 API のレスポンスを記載する。
 
@@ -372,12 +372,7 @@ components:
         ...
   responses:
     BadRequest:
-      description: Bad Request
-      content:
-        application/json:
-          schema:
-            ...
-    ...
+      ...
 ```
 
 ### security
@@ -460,6 +455,70 @@ components:
       ...
 ```
 
+#### responses(components)
+
+レスポンスで複数のエンドポイントで横断的に用いるモデルを定義する。例えば、ステータスコード400~500系のエラーモデルがある。
+​
+```yml
+components:
+  schemas:
+    ProblemDetailError:
+      type: object
+      properties:
+        ...
+  responses:
+    BadRequest:
+      description: 400 Bad Request
+      content:
+        application/json:
+          schema:
+            "$ref": "#/components/schemas/ProblemDetailError"
+    Unauthorized:
+      description: 401 Unauthorized
+      content:
+        application/json:
+          schema:
+            "$ref": "#/components/schemas/ProblemDetailError"
+    ...
+```
+​
+もし、正常系のレスポンスの例としてはファイルアップロード・ダウンロードなどが該当する。個別のアプリケーション要件でブレが少ないと複数のエンドポイントで用いられる場合に定義する。
+
+```yml
+components:
+  schemas:
+    SignedURL:
+      type: object
+      properties:
+        signed_url:
+          type: string
+          format: uri
+        expired_at:
+          type: string
+          format: date-time
+  responses:
+    BlobUpload:
+      description: BLOB(Binary Large Object) upload using presigned url
+      content:
+        application/json:
+          schema:
+            "$ref": "#/components/schemas/SignedURL"
+    BlobDownload:
+      description: BLOB(Binary Large Object) download using presigned url
+      content:
+        application/json:
+          schema:
+            "$ref": "#/components/schemas/SignedURL"
+    ImageBinary:
+      description: An image
+      content:
+        image/*:
+          schema:
+            type: string
+            format: binary
+
+```
+
 
 #### parameters(components)