From d52166e60a9b7fa1c2399538f3ffbaffbcfacb6d Mon Sep 17 00:00:00 2001
From: Hiroki Takeda <takeda.hiroki.tech@gmail.com>
Date: Tue, 12 Dec 2023 00:30:56 +0900
Subject: [PATCH 1/2] Add parameters

---
 .../OpenAPI_Specification_3.0.3.md            | 62 ++++++++++++++-----
 1 file changed, 48 insertions(+), 14 deletions(-)

diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md
index a89919c9..c3c4c069 100644
--- a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md
+++ b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md
@@ -550,29 +550,63 @@ components:
               $ref: './examples/post-product.example.1.yaml'
 ```
 
-#### parameters(components)
+#### parameters
 
-API 共通で利用するクエリパラメータを定義
+API 共通で利用するパラメータ（パスパラメータ、クエリパラメータ、ヘッダ, Cookie）を記載する。
+
+##### パスパラメータ
+
+* API 全体で利用されるパスパラメータが必要なケースが想定されないため、原則定義しない。
+特定リソースの操作（例えば更新と削除）を行う際のリソースIDはパスパラメータとして再利用できるが、コンフリクトを避けるため原則共通化は行わない。
+
+##### クエリパラメータ
+
+* API 全体で利用可能な共通のクエリパラメータを定義する （例: 検索数のlimit, offset）
+* 命名は クエリパラメータ名に `Query` というプレフィクスを付与する形式を推奨する。
 
-* 規約
-    * [ ] API 全体で利用可能な共通のクエリパラメータを定義 (例: 検索数のlimit,offset)
 
 ```yml
+paths:
+  get:
+    /products:
+      parameters:
+        - $ref: '#/components/parameters/QueryLimit'
+
 parameters:
-    limit:
-      name: limit
-      in: query
-      required: false
-      schema:
-        type: integer
-      description: 検索数上限
-
-# 利用方法
+  QueryLimit:
+    name: limit
+    in: query
+    required: false
+    schema:
+      type: integer
+    description: 検索数上限
+```
+
+##### ヘッダパラメータ
+
+* 原則 `headers` を利用し、パラメータとしては定義しない。
+
+##### Cookie パラメータ
+
+* API 全体で利用可能な共通のCookieパラメータを定義する。（例: CSRF用のトークン）
+* 命名は Cookie パラメータ名に `Cookie` というプレフィクスを付与する形式を推奨する。
+* Cookie 認証を定義する場合は、`APIKey` を利用すること。
+
+```yml
 paths:
   get:
     /products:
       parameters:
-        - $ref: '#/components/parameters/limit'
+        - $ref: '#/components/parameters/CookieCSRFToken'
+
+parameters:
+  CSRFToken:
+    name: csrftoken
+    in: cookie
+    required: true
+    schema:
+      type: string
+    description: CSRFトークン
 ```
 
 ### securitySchemes

From a5566835919e2b2ed47c156f360c67058d42181f Mon Sep 17 00:00:00 2001
From: Hiroki Takeda <takeda.hiroki.tech@gmail.com>
Date: Fri, 22 Dec 2023 13:13:27 +0900
Subject: [PATCH 2/2] fix: fix a typo

---
 .../forOpenAPISpecification/OpenAPI_Specification_3.0.3.md      | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md
index c3c4c069..758145c1 100644
--- a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md
+++ b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md
@@ -600,7 +600,7 @@ paths:
         - $ref: '#/components/parameters/CookieCSRFToken'
 
 parameters:
-  CSRFToken:
+  CookieCSRFToken:
     name: csrftoken
     in: cookie
     required: true