From 693f577c0401d041fa42ecbb0feb816e11cc23ba Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Mon, 20 Jul 2020 23:29:39 +0900
Subject: [PATCH 01/34] feat: separate tags into "article" and "revision"

---
 swagger.yaml | 36 ++++++++++++++++++------------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/swagger.yaml b/swagger.yaml
index 5685d29..118e899 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -195,7 +195,7 @@ paths:
     get:
       summary: get list of articles
       tags:
-      - blog
+      - blog article
       parameters:
       - in: query
         name: filter
@@ -259,7 +259,7 @@ paths:
     get:
       summary: get info of the article
       tags:
-      - blog
+      - blog article
       responses:
         200:
           description: article info
@@ -291,7 +291,7 @@ paths:
       security:
       - admin: []
       tags:
-      - blog
+      - blog article
       requestBody:
         description: data to update
         content:
@@ -328,7 +328,7 @@ paths:
       security:
       - admin: []
       tags:
-      - blog
+      - blog article
       responses:
         204:
           description: remove successful
@@ -344,7 +344,7 @@ paths:
     put:
       summary: give "good" to article
       tags:
-      - blog
+      -  blog article
       responses:
         200:
           description: success
@@ -363,7 +363,7 @@ paths:
     delete:
       summary: remove "good" from article
       tags:
-      - blog
+      - blog article
       responses:
         200:
           description: successfully removed
@@ -386,7 +386,7 @@ paths:
     put:
       summary: give "bad" to article
       tags:
-      - blog
+      - blog article
       responses:
         200:
           description: success
@@ -405,7 +405,7 @@ paths:
     delete:
       summary: remove "bad" from article
       tags:
-      - blog
+      - blog article
       responses:
         200:
           description: successfully removed
@@ -427,7 +427,7 @@ paths:
       summary: get list of revisions
       description: "note: writer can see only owned revision"
       tags:
-      - blog
+      - blog revision
       security:
       - admin: []
       - blogWriter: []
@@ -462,7 +462,7 @@ paths:
     post:
       summary: create new revision
       tags:
-      - blog
+      - blog revision
       security:
       - blogWriter: []
       requestBody:
@@ -488,7 +488,7 @@ paths:
     post:
       summary: create new contrib
       tags:
-      - blog
+      - blog revision
       requestBody:
         description: params to filter
         content:
@@ -519,7 +519,7 @@ paths:
       summary: get the revision
       description: "note: writer can see only owned revision"
       tags:
-      - blog
+      - blog revision
       security:
       - admin: []
       - blogWriter: []
@@ -548,7 +548,7 @@ paths:
       summary: edit the revision
       description: create new revision based on the specific revision
       tags:
-      - blog
+      - blog revision
       security:
       - admin: []
       requestBody:
@@ -569,7 +569,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-      
+
   /blog/revisions/{id}/accept:
     parameters:
     - $ref: "#/components/parameters/blogRevisionId"
@@ -578,7 +578,7 @@ paths:
       security:
       - admin: []
       tags:
-      - blog
+      - blog revision
       responses:
         200:
           description: operation successful
@@ -600,7 +600,7 @@ paths:
       security:
       - admin: []
       tags:
-      - blog
+      - blog revision
       responses:
         200:
           description: operation successful
@@ -618,7 +618,7 @@ paths:
     get:
       summary: get list of categories
       tags:
-      - blog
+      - blog revision
       responses:
         200:
           description: list of categories
@@ -636,7 +636,7 @@ paths:
                         name of category
                     visible:
                       type: boolean
-                      description: 
+                      description:
                         whether should be shown on the top page
 
   /images:

From 1c57f0f8a1d612de2448c8b14015e279506296c0 Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Mon, 20 Jul 2020 23:35:35 +0900
Subject: [PATCH 02/34] refactor: delete mysterious space

---
 swagger.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/swagger.yaml b/swagger.yaml
index 118e899..d8c316f 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -379,7 +379,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-  
+
   /blog/articles/{id}/bad:
     parameters:
     - $ref: "#/components/parameters/blogArticleId"

From e66873626bdc1b1419d07ccf0c19f2c24a30b36e Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Tue, 21 Jul 2020 21:36:56 +0900
Subject: [PATCH 03/34] docs: change title

---
 README.md    | 2 +-
 swagger.yaml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index d8235d0..2fd5e97 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# 73rd AzabuFes official website api documentation
+# 73rd Afes website API documentation
 ![](https://img.shields.io/badge/dynamic/yaml?color=007ec6&label=version&style=for-the-badge&query=$.info.version&url=https://raw.githubusercontent.com/afes-website/docs/develop/swagger.yaml)
 
 ![Swagger](https://img.shields.io/badge/-Swagger-6d9a00.svg?logo=swagger&logoColor=fff&style=flat-square)
diff --git a/swagger.yaml b/swagger.yaml
index d8c316f..b28bcf0 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -1,7 +1,7 @@
 openapi: 3.0.0
 info:
   version: 1.7.0
-  title: Afes73 website API
+  title: 73rd Afes website api
 servers:
 - url: https://api.afes.info/
 - url: http://localhost:8000/ # for local test

From a9d76e3c582bde1eadc319eb84f6d29fd57876b5 Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Tue, 21 Jul 2020 21:39:24 +0900
Subject: [PATCH 04/34] fix: fix /blog/categories tag and update position

---
 swagger.yaml | 49 +++++++++++++++++++++++++------------------------
 1 file changed, 25 insertions(+), 24 deletions(-)

diff --git a/swagger.yaml b/swagger.yaml
index b28bcf0..d3805da 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -422,6 +422,31 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
 
+  /blog/categories/:
+    get:
+      summary: get list of categories
+      tags:
+      - blog article
+      responses:
+        200:
+          description: list of categories
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties:
+                  description: id of category
+                  type: object
+                  properties:
+                    name:
+                      type: string
+                      description:
+                        name of category
+                    visible:
+                      type: boolean
+                      description:
+                        whether should be shown on the top page
+
   /blog/revisions/:
     get:
       summary: get list of revisions
@@ -614,30 +639,6 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-  /blog/categories/:
-    get:
-      summary: get list of categories
-      tags:
-      - blog revision
-      responses:
-        200:
-          description: list of categories
-          content:
-            application/json:
-              schema:
-                type: object
-                additionalProperties:
-                  description: id of category
-                  type: object
-                  properties:
-                    name:
-                      type: string
-                      description:
-                        name of category
-                    visible:
-                      type: boolean
-                      description:
-                        whether should be shown on the top page
 
   /images:
     post:

From 18eaab1d1894341f2007c95cc2a6490ef63115b8 Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Wed, 22 Jul 2020 10:06:27 +0900
Subject: [PATCH 05/34] docs: translate to Japanese in AdminAuth path

---
 swagger.yaml | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/swagger.yaml b/swagger.yaml
index d3805da..0a507eb 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -9,11 +9,11 @@ servers:
 paths:
   /admin/login:
     post:
-      summary: Login and get API Key
+      summary: ログイン認証とAPIキーの受け取り
       tags:
       - admin auth
       requestBody:
-        description: credentials
+        description: 認証情報
         content:
           application/json:
             schema:
@@ -28,7 +28,7 @@ paths:
                   type: string
       responses:
         200:
-          description: Login Successful
+          description: ログイン成功
           content:
             application/json:
               schema:
@@ -37,27 +37,27 @@ paths:
                   token:
                     type: string
         401:
-          description: Login failed
+          description: idかパスワードが間違っています
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
         429:
-          description: Too many login attempts
+          description: 試行回数の上限に達しました
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
   /admin/user:
     get:
-      summary: get logged in user info
+      summary: ログイン中のAdminの情報の取得
       tags:
       - admin auth
       security:
       - admin: []
       responses:
         200:
-          description: User info (logged in)
+          description: ログイン中のAdminユーザー情報
           content:
             application/json:
               schema:
@@ -71,20 +71,20 @@ paths:
                   name:
                     type: string
         401:
-          description: Not logged in
+          description: ログインしていません
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
   /admin/change_password:
     post:
-      summary: Change password
+      summary: パスワード変更
       tags:
       - admin auth
       security:
       - admin: []
       requestBody:
-        description: new password
+        description: 新しいパスワード
         content:
           application/json:
             schema:
@@ -96,9 +96,9 @@ paths:
                   type: string
       responses:
         204:
-          description: password changed successfully
+          description: パスワードを変更しました
         400:
-          description: bad password
+          description: 新しいパスワードが条件を満たしていません
   /writer/login:
     post:
       summary: Login and get API Key

From effea0a6ff29aace0b94f40f9678a7f6fb51172e Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Wed, 22 Jul 2020 10:15:13 +0900
Subject: [PATCH 06/34] feat: add description

---
 swagger.yaml | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/swagger.yaml b/swagger.yaml
index 0a507eb..1e5cd23 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -10,6 +10,7 @@ paths:
   /admin/login:
     post:
       summary: ログイン認証とAPIキーの受け取り
+      description: 5回/分まで試行できます
       tags:
       - admin auth
       requestBody:
@@ -28,7 +29,7 @@ paths:
                   type: string
       responses:
         200:
-          description: ログイン成功
+          description: Admin api token
           content:
             application/json:
               schema:
@@ -51,6 +52,7 @@ paths:
   /admin/user:
     get:
       summary: ログイン中のAdminの情報の取得
+      description: AdminのAPI KEYから、ログイン中のアカウントのidのnameを取得します
       tags:
       - admin auth
       security:
@@ -71,7 +73,7 @@ paths:
                   name:
                     type: string
         401:
-          description: ログインしていません
+          description: ログインしていません; 無効なAdmin Tokenです
           content:
             application/json:
               schema:
@@ -84,7 +86,7 @@ paths:
       security:
       - admin: []
       requestBody:
-        description: 新しいパスワード
+        description: 新しいパスワード(8文字以上)
         content:
           application/json:
             schema:

From 1403d9d49d6bb9709fbd60028efef34f92aa3510 Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Wed, 22 Jul 2020 10:24:10 +0900
Subject: [PATCH 07/34] style: remove and add blank line

---
 swagger.yaml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/swagger.yaml b/swagger.yaml
index 1e5cd23..8f9fab3 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -101,6 +101,7 @@ paths:
           description: パスワードを変更しました
         400:
           description: 新しいパスワードが条件を満たしていません
+
   /writer/login:
     post:
       summary: Login and get API Key
@@ -193,6 +194,7 @@ paths:
           description: password changed successfully
         400:
           description: bad password
+
   /blog/articles:
     get:
       summary: get list of articles
@@ -381,7 +383,6 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-
   /blog/articles/{id}/bad:
     parameters:
     - $ref: "#/components/parameters/blogArticleId"
@@ -423,7 +424,6 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-
   /blog/categories/:
     get:
       summary: get list of categories
@@ -563,8 +563,6 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-
-
         404:
           description: no sprcified revision found
           content:
@@ -596,7 +594,6 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-
   /blog/revisions/{id}/accept:
     parameters:
     - $ref: "#/components/parameters/blogRevisionId"
@@ -724,6 +721,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
+
   /ogimage:
     get:
       summary: generate og image for static page
@@ -914,6 +912,7 @@ components:
       - user_id
       - timestamp
       - status
+
   parameters:
     blogArticleId:
       in: path
@@ -930,6 +929,7 @@ components:
         type: integer
         format: int32
       description: id of a revision
+
   securitySchemes:
     admin:
       type: apiKey

From 3bea5f41e0e30cf62d52c6b954de62754bfd987c Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Wed, 22 Jul 2020 18:59:50 +0900
Subject: [PATCH 08/34] fix: change description's expression

---
 swagger.yaml | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/swagger.yaml b/swagger.yaml
index 8f9fab3..90a20f8 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -9,8 +9,8 @@ servers:
 paths:
   /admin/login:
     post:
-      summary: ログイン認証とAPIキーの受け取り
-      description: 5回/分まで試行できます
+      summary: ログイン認証と API キーの受け取り
+      description: 5回/分まで試行可能
       tags:
       - admin auth
       requestBody:
@@ -38,28 +38,28 @@ paths:
                   token:
                     type: string
         401:
-          description: idかパスワードが間違っています
+          description: 認証失敗
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
         429:
-          description: 試行回数の上限に達しました
+          description: 試行回数の上限に到達
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
   /admin/user:
     get:
-      summary: ログイン中のAdminの情報の取得
-      description: AdminのAPI KEYから、ログイン中のアカウントのidのnameを取得します
+      summary: ログイン中の Admin の情報の取得
+      description: Admin の API KEY から、アカウント情報を取得
       tags:
       - admin auth
       security:
       - admin: []
       responses:
         200:
-          description: ログイン中のAdminユーザー情報
+          description: ログイン中の Admin ユーザー情報
           content:
             application/json:
               schema:
@@ -73,7 +73,7 @@ paths:
                   name:
                     type: string
         401:
-          description: ログインしていません; 無効なAdmin Tokenです
+          description: Admin Token が無効
           content:
             application/json:
               schema:
@@ -98,9 +98,9 @@ paths:
                   type: string
       responses:
         204:
-          description: パスワードを変更しました
+          description: 処理完了
         400:
-          description: 新しいパスワードが条件を満たしていません
+          description: 新しいパスワードが条件を満たしていない
 
   /writer/login:
     post:

From c754ad05183a07345ce11ff2b1a02c617c6855f1 Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Wed, 22 Jul 2020 19:00:47 +0900
Subject: [PATCH 09/34] docs: reword in WriterAuth path

---
 swagger.yaml | 23 ++++++++++++-----------
 1 file changed, 12 insertions(+), 11 deletions(-)

diff --git a/swagger.yaml b/swagger.yaml
index 90a20f8..0dfd7b9 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -104,11 +104,11 @@ paths:
 
   /writer/login:
     post:
-      summary: Login and get API Key
+      summary: ログイン認証と API キーの受け取り
       tags:
       - writer auth
       requestBody:
-        description: credentials
+        description: 認証情報
         content:
           application/json:
             schema:
@@ -123,7 +123,7 @@ paths:
                   type: string
       responses:
         200:
-          description: Login Successful
+          description: Admin api token
           content:
             application/json:
               schema:
@@ -132,27 +132,28 @@ paths:
                   token:
                     type: string
         401:
-          description: Login failed
+          description: 認証失敗
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
         429:
-          description: Too many login attempts
+          description: 試行回数の上限に到達
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
   /writer/user:
     get:
-      summary: get logged in user info
+      summary: ログイン中の Writer の情報の取得
+      description: Writer の API KEY から、アカウント情報を取得
       tags:
       - writer auth
       security:
       - blogWriter: []
       responses:
         200:
-          description: User info (logged in)
+          description: ログイン中のAdminユーザー情報
           content:
             application/json:
               schema:
@@ -173,13 +174,13 @@ paths:
                 $ref: "#/components/schemas/Error"
   /writer/change_password:
     post:
-      summary: Change password
+      summary: パスワード変更
       tags:
       - writer auth
       security:
       - blogWriter: []
       requestBody:
-        description: new password
+        description: 新しいパスワード(8文字以上)
         content:
           application/json:
             schema:
@@ -191,9 +192,9 @@ paths:
                   type: string
       responses:
         204:
-          description: password changed successfully
+          description: 処理完了
         400:
-          description: bad password
+          description: 新しいパスワードが条件を満たしていない
 
   /blog/articles:
     get:

From dc8ee23810ff5c2e1effac0799c3bf395087c354 Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Wed, 22 Jul 2020 19:46:41 +0900
Subject: [PATCH 10/34] docs: reword in /blog/articles/

---
 swagger.yaml | 24 +++++++++++++++---------
 1 file changed, 15 insertions(+), 9 deletions(-)

diff --git a/swagger.yaml b/swagger.yaml
index 0dfd7b9..f6252e2 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -198,7 +198,7 @@ paths:
 
   /blog/articles:
     get:
-      summary: get list of articles
+      summary: article のリストを取得
       tags:
       - blog article
       parameters:
@@ -213,26 +213,31 @@ paths:
         style: form
         explode: true
         required: false
-        description: params to filter
+        description: |
+          article の検索条件
+          AND 検索
       - in: query
         name: summary_length
         schema:
           type: integer
         style: form
         required: false
-        description: >
-          summary will be cut with this length.
-          if omitted, summary won't be limited with length.
+        description: |
+          指定すると、 summary がarticle 本文の指定字数分の部分文字列になる
+          指定しない場合、 summary は article の本文 (content) と同一
       - in: query
         name: q
         schema:
           type: string
         description: |
-          search query
-          article has match in title or content will be returned
+          検索クエリ
+          title, content から検索
+          filter との AND 検索
       responses:
         200:
-          description: list of articles
+          description: |
+            検索条件をすべて満たした article の配列
+            該当するものがない場合は空の配列
           content:
             application/json:
               schema:
@@ -243,6 +248,7 @@ paths:
                   - properties:
                       summary:
                         type: string
+                        description: article 本文より、先頭から summary_length 字分の部分文字列
                   - required:
                     - id
                     - user_id
@@ -253,7 +259,7 @@ paths:
                     - updated_at
                     - summary
         400:
-          description: bad params
+          description: 誤ったパラメータが含まれている
           content:
             application/json:
               schema:

From 9d3007fed91580de6f28101c1aa59370b41699f1 Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Fri, 24 Jul 2020 17:39:08 +0900
Subject: [PATCH 11/34] docs: reword in /blog/articles/{id}

---
 swagger.yaml | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/swagger.yaml b/swagger.yaml
index f6252e2..049ac5d 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -268,12 +268,12 @@ paths:
     parameters:
     - $ref: "#/components/parameters/blogArticleId"
     get:
-      summary: get info of the article
+      summary: article の情報を返す
       tags:
       - blog article
       responses:
         200:
-          description: article info
+          description: article の情報
           content:
             application/json:
               schema:
@@ -292,59 +292,63 @@ paths:
                   - updated_at
                   - content
         404:
-          description: no article found
+          description: id に該当する article が存在しない
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
     patch:
-      summary: update the article
+      summary: article を更新する
+      description: |
+        article に対応する要素を渡す事で更新する事ができる
+        一部の要素のみを渡すと、渡された要素のみを更新する
       security:
       - admin: []
       tags:
       - blog article
       requestBody:
-        description: data to update
+        description: 更新したいデータ
         content:
           application/json:
             schema:
               $ref: "#/components/schemas/BlogArticle"
       responses:
         200:
-          description: info of specified revision
+          description: 新しい article の情報
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/BlogArticle"
         400:
-          description: specified revision is not for the article
+          description: 指定された revision の article_id とパスの article_id が一致しない
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
         404:
-          description: no sprcified revision found
+          description: 指定された revision は存在しない
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
         409:
-          description: specified revision is not accepted
+          description: 指定された revision の状態が accepted でない
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
     delete:
-      summary: remove the article
+      summary: article を削除する
+      description: article オブジェクトを削除するのみで revision は削除されない
       security:
       - admin: []
       tags:
       - blog article
       responses:
         204:
-          description: remove successful
+          description: 削除完了 返り値なし
         404:
-          description: no specified revision found
+          description: 指定された article が存在しない
           content:
             application/json:
               schema:

From 2d8f19df9f04956e1900d5925fd4b69f6da6e21a Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Sat, 25 Jul 2020 23:08:29 +0900
Subject: [PATCH 12/34] docs: reword the other of blogArticle

---
 swagger.yaml | 43 ++++++++++++++++++++++---------------------
 1 file changed, 22 insertions(+), 21 deletions(-)

diff --git a/swagger.yaml b/swagger.yaml
index 049ac5d..9584cee 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -357,39 +357,39 @@ paths:
     parameters:
     - $ref: "#/components/parameters/blogArticleId"
     put:
-      summary: give "good" to article
+      summary: article に対して good を押す
       tags:
       -  blog article
       responses:
         200:
-          description: success
+          description: 成功 返り値なし
         404:
-          description: no article found
+          description: 該当の article が存在しない
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
         429:
-          description: Too many attempts
+          description: リクエスト過多
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
     delete:
-      summary: remove "good" from article
+      summary: article から good を1つ除去する
       tags:
       - blog article
       responses:
         200:
-          description: successfully removed
+          description: 成功 返り値なし
         404:
-          description: no article found
+          description: 該当する article が存在しない
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
         429:
-          description: Too many attempts
+          description: リクエスト過多(具体的な値は未定)
           content:
             application/json:
               schema:
@@ -398,67 +398,68 @@ paths:
     parameters:
     - $ref: "#/components/parameters/blogArticleId"
     put:
-      summary: give "bad" to article
+      summary: article に対して bad を押す
       tags:
       - blog article
       responses:
         200:
-          description: success
+          description: 成功 返り値なし
         404:
-          description: no article found
+          description: 該当する article が存在しない
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
         429:
-          description: Too many attempts
+          description: リクエスト過多(具体的な値は未定)
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
     delete:
-      summary: remove "bad" from article
+      summary: article から bad を1つ除去する
       tags:
       - blog article
       responses:
         200:
           description: successfully removed
         404:
-          description: no article found
+          description: 該当する article が存在しない
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
         429:
-          description: Too many attempts
+          description: リクエスト過多(具体的な値は未定)
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
   /blog/categories/:
     get:
-      summary: get list of categories
+      summary: category のリストを取得する
       tags:
       - blog article
       responses:
         200:
-          description: list of categories
+          description: category のリスト
           content:
             application/json:
               schema:
                 type: object
                 additionalProperties:
-                  description: id of category
+                  description: category の ID
                   type: object
                   properties:
                     name:
                       type: string
                       description:
-                        name of category
+                        category の名前
                     visible:
                       type: boolean
-                      description:
-                        whether should be shown on the top page
+                      description: |
+                        top ページのカテゴリー一覧にて表示するか否か
+                        通常、公開されているかどうかを示しています。
 
   /blog/revisions/:
     get:

From 8fa587c0e3cf539907e5c295339de5fc9d300ee9 Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Sun, 26 Jul 2020 12:04:19 +0900
Subject: [PATCH 13/34] docs: reword in the other of swagger

---
 swagger.yaml | 130 +++++++++++++++++++++++++++++++--------------------
 1 file changed, 79 insertions(+), 51 deletions(-)

diff --git a/swagger.yaml b/swagger.yaml
index 9584cee..92e6596 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -422,7 +422,7 @@ paths:
       - blog article
       responses:
         200:
-          description: successfully removed
+          description: 成功 返り値なし
         404:
           description: 該当する article が存在しない
           content:
@@ -463,8 +463,10 @@ paths:
 
   /blog/revisions/:
     get:
-      summary: get list of revisions
-      description: "note: writer can see only owned revision"
+      summary: revision のリストを取得
+      description: |
+        admin の場合は 全 revision を取得できる
+        writer の場合は revision の author と writer の ID が一致するもののみ取得できる
       tags:
       - blog revision
       security:
@@ -482,10 +484,14 @@ paths:
         style: form
         explode: true
         required: false
-        description: params to filter
+        description: |
+          revision の検索条件
+          AND 検索
       responses:
         200:
-          description: list of revisions
+          description: |
+            検索条件をすべて満たした revision の配列
+            該当するものがない場合は空の配列
           content:
             application/json:
               schema:
@@ -493,43 +499,48 @@ paths:
                 items:
                   $ref: "#/components/schemas/BlogRevision"
         400:
-          description: bad params
+          description: 誤ったパラメータが含まれている
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
     post:
-      summary: create new revision
+      summary: 新しい revision を作る
       tags:
       - blog revision
       security:
       - blogWriter: []
       requestBody:
-        description: params to filter
+        description: 作成したい revision の情報
         content:
           application/json:
             schema:
               $ref: "#/components/schemas/BlogRevision"
       responses:
         201:
-          description: created
+          description: 完了
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/BlogRevision"
         400:
-          description: some params are invalid
+          description: パラメータに過不足がある
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
   /blog/revisions/contrib/:
     post:
-      summary: create new contrib
+      summary: 寄稿を投稿する
+      description: |
+        投稿された寄稿は「名もなき麻布生」名義で revision として作成される
+        「名もなき麻布生」 は ID anonymous, password は空文字列のものを用意する
       tags:
       - blog revision
       requestBody:
-        description: params to filter
+        description: |
+          投稿したい寄稿の情報
+          article_id: バックエンド側で重複しないように「contrib_(英数列5文字)」となるように設定する
         content:
           application/json:
             schema:
@@ -540,13 +551,13 @@ paths:
                     readOnly: true
       responses:
         201:
-          description: created
+          description: 投稿完了
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/BlogRevision"
         400:
-          description: some params are invalid
+          description: パラメータに誤りがある
           content:
             application/json:
               schema:
@@ -555,8 +566,8 @@ paths:
     parameters:
     - $ref: "#/components/parameters/blogRevisionId"
     get:
-      summary: get the revision
-      description: "note: writer can see only owned revision"
+      summary: revision を取得する
+      description: writer の場合、user_id が一致していない revision は取得できない
       tags:
       - blog revision
       security:
@@ -564,44 +575,49 @@ paths:
       - blogWriter: []
       responses:
         200:
-          description: info of specified revision
+          description: revision の情報
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/BlogRevision"
         403:
-          description: the revision could not be seen by the user
+          description: 該当する revision の閲覧権限がない
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
         404:
-          description: no sprcified revision found
+          description: 該当する revision が存在しない
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
     post:
-      summary: edit the revision
-      description: create new revision based on the specific revision
+      summary: revision を編集する
+      description: |
+        指定された revision を元に新たに revision を作成する
+        指定された元の revision は更新されない
       tags:
       - blog revision
       security:
       - admin: []
       requestBody:
+        description: |
+          更新したい情報
+          指定されなかった要素がある場合は、元の revision と同一の内容になる
         content:
           application/json:
             schema:
               $ref: "#/components/schemas/BlogRevision"
       responses:
         201:
-          description: created
+          description: 新しい revision の情報
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/BlogRevision"
         400:
-          description: some params are invalid
+          description: パラメータに不備がある
           content:
             application/json:
               schema:
@@ -610,14 +626,15 @@ paths:
     parameters:
     - $ref: "#/components/parameters/blogRevisionId"
     patch:
-      summary: accept the revision
+      summary: revision を承認する
+      description: revision の status を accept にする
       security:
       - admin: []
       tags:
       - blog revision
       responses:
         200:
-          description: operation successful
+          description: 新しい revision の情報
           content:
             application/json:
               schema:
@@ -632,20 +649,20 @@ paths:
     parameters:
     - $ref: "#/components/parameters/blogRevisionId"
     patch:
-      summary: reject the revision
+      summary: revision を拒否する
       security:
       - admin: []
       tags:
       - blog revision
       responses:
         200:
-          description: operation successful
+          description: 成功
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/BlogRevision"
         404:
-          description: no specified revision found
+          description: 該当する revision が存在しない
           content:
             application/json:
               schema:
@@ -653,13 +670,13 @@ paths:
 
   /images:
     post:
-      summary: upload new image
+      summary: 新しい imgae を投稿する
       tags:
       - images
       security:
       - blogWriter: []
       requestBody:
-        description: params to filter
+        description: image の情報
         content:
           multipart/form-data:
             schema:
@@ -672,7 +689,9 @@ paths:
               - content
       responses:
         201:
-          description: created
+          description: |
+            image の id
+            id: 自動生成のランダムな40文字の英数列
           content:
             application/json:
               schema:
@@ -683,14 +702,19 @@ paths:
                 required:
                 - id
         400:
-          description: some params are invalid / content is not an image
+          description: パラメータに問題があるが、アップロードされたものが画像でない
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
   /images/{id}:
     get:
-      summary: get image
+      summary: |
+        id から image を取得する
+        original を指定すると、アップロードされた元ファイルの画像が取得される
+        幅・高さの両方を指定すると、縦横でそれぞれ拡大縮小をする
+        幅・高さの片方を指定すると、画像全体を適切に拡大縮小する
+        すべて指定しない場合は、縦幅が最大600、横幅が最大1080になるように設定される
       tags:
       - images
       parameters:
@@ -699,26 +723,26 @@ paths:
         required: true
         schema:
           type: string
-        description: id of an image
+        description: image の id
       - in: query
         name: w
         required: false
         schema:
           type: integer
-        description: width of image
+        description: image の幅
       - in: query
         name: h
         required: false
         schema:
           type: integer
-        description: height of image
+        description: image の高さ
       - in: query
         name: orig
         required: false
         schema:
           type: string
           enum: ['yes']
-        description: whether you want to get original image
+        description: オリジナルの画像を取得するかどうか
       responses:
         200:
           description: content
@@ -728,7 +752,7 @@ paths:
                 type: string
                 format: binary
         404:
-          description: not found
+          description: 指定された image が存在しない
           content:
             application/json:
               schema:
@@ -736,32 +760,33 @@ paths:
 
   /ogimage:
     get:
-      summary: generate og image for static page
+      summary: 固定ページ用の ogimage を生成する
       tags:
       - ogimage
       parameters:
       - in: query
         name: title
+        description: タイトル `\n`または改行コードで改行
         required: true
         schema:
           type: string
       responses:
         200:
-          description: image
+          description: 画像
           content:
             image/*:
               schema:
                 type: string
                 format: binary
         400:
-          description: bad params
+          description: パラメータに不備がある
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
   /ogimage/articles/{id}:
     get:
-      summary: generate og image from article data
+      summary: article から ogimage を生成する
       tags:
       - ogimage
       parameters:
@@ -770,30 +795,33 @@ paths:
         required: true
         schema:
           type: string
-        description: id of article
+        description: article の id
       responses:
         200:
-          description: image
+          description: |
+            画像
+            title: `\n`または改行コードが含まれている場合改行される
+            author: article に handle_name が設定されている場合、 handle_name が代わりに表示される
           content:
             image/*:
               schema:
                 type: string
                 format: binary
         400:
-          description: bad params
+          description: パラメータに不備がある
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
         404:
-          description: no article found
+          description: 該当する article が存在しない
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
   /ogimage/preview:
     get:
-      summary: generate og image from param data
+      summary: ogimage を指定されたパラメータから生成する
       tags:
       - ogimage
       parameters:
@@ -802,13 +830,13 @@ paths:
         required: true
         schema:
           type: string
-        description: title
+        description: title `\n`または改行コードで改行
       - in: query
         name: author
         required: false
         schema:
           type: string
-        description: author
+        description: author (handle_name 設定時は handle_name)
       - in: query
         name: category
         required: false
@@ -817,14 +845,14 @@ paths:
         description: category
       responses:
         200:
-          description: image
+          description: 画像
           content:
             image/*:
               schema:
                 type: string
                 format: binary
         400:
-          description: bad params
+          description: パラメータに不備がある
           content:
             application/json:
               schema:

From 1d611dbb33608624b0bccc6957782670a20e323f Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Sun, 26 Jul 2020 12:29:10 +0900
Subject: [PATCH 14/34] fix: set readOnly in article timestamp

---
 swagger.yaml | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/swagger.yaml b/swagger.yaml
index 92e6596..5a103f3 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -210,6 +210,10 @@ paths:
           - properties:
               author_id:
                 type: string
+              created_at:
+                readOnly: true
+              updated_at:
+                readOnly: true
         style: form
         explode: true
         required: false
@@ -904,9 +908,11 @@ components:
         created_at:
           type: string
           format: date-time
+          readOnly: true
         updated_at:
           type: string
           format: date-time
+          readOnly: true
     BlogRevision:
       type: object
       properties:

From fe9329ac9083cf390db2e3a2447cdcab3c5a0a16 Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Sun, 26 Jul 2020 12:34:37 +0900
Subject: [PATCH 15/34] fix: disable readOnly "timestamp" in revision index

---
 swagger.yaml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/swagger.yaml b/swagger.yaml
index 5a103f3..b88ecab 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -485,6 +485,8 @@ paths:
             - properties:
                 author_id:
                   type: string
+                timestamp:
+                  readOnly: false
         style: form
         explode: true
         required: false

From e9fc26900293f130e113085efe7ead915389ab40 Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Sun, 26 Jul 2020 12:47:39 +0900
Subject: [PATCH 16/34] fix: move to description from /image/{id} get

Co-Authored-By: subaru <contact@su8ru.dev>
---
 swagger.yaml | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/swagger.yaml b/swagger.yaml
index b88ecab..b556639 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -715,12 +715,12 @@ paths:
                 $ref: "#/components/schemas/Error"
   /images/{id}:
     get:
-      summary: |
-        id から image を取得する
-        original を指定すると、アップロードされた元ファイルの画像が取得される
-        幅・高さの両方を指定すると、縦横でそれぞれ拡大縮小をする
-        幅・高さの片方を指定すると、画像全体を適切に拡大縮小する
-        すべて指定しない場合は、縦幅が最大600、横幅が最大1080になるように設定される
+      summary: id から image を取得する
+      description: |
+        original を指定すると、アップロードされた元ファイルの画像が取得される  
+        幅・高さの両方を指定すると、縦横でそれぞれ拡大縮小をする  
+        幅・高さの片方を指定すると、画像全体を適切に拡大縮小する  
+        すべて指定しない場合は、縦幅が最大600、横幅が最大1080になるように設定される  
       tags:
       - images
       parameters:

From b4dc10a1a7871d4a75e1c0c3f22457767554b516 Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Sun, 26 Jul 2020 12:49:22 +0900
Subject: [PATCH 17/34] fix: add space in multi-line description

---
 swagger.yaml | 32 ++++++++++++++++----------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/swagger.yaml b/swagger.yaml
index b556639..660de3b 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -218,7 +218,7 @@ paths:
         explode: true
         required: false
         description: |
-          article の検索条件
+          article の検索条件  
           AND 検索
       - in: query
         name: summary_length
@@ -227,20 +227,20 @@ paths:
         style: form
         required: false
         description: |
-          指定すると、 summary がarticle 本文の指定字数分の部分文字列になる
+          指定すると、 summary がarticle 本文の指定字数分の部分文字列になる  
           指定しない場合、 summary は article の本文 (content) と同一
       - in: query
         name: q
         schema:
           type: string
         description: |
-          検索クエリ
-          title, content から検索
+          検索クエリ  
+          title, content から検索  
           filter との AND 検索
       responses:
         200:
           description: |
-            検索条件をすべて満たした article の配列
+            検索条件をすべて満たした article の配列  
             該当するものがない場合は空の配列
           content:
             application/json:
@@ -304,7 +304,7 @@ paths:
     patch:
       summary: article を更新する
       description: |
-        article に対応する要素を渡す事で更新する事ができる
+        article に対応する要素を渡す事で更新する事ができる  
         一部の要素のみを渡すと、渡された要素のみを更新する
       security:
       - admin: []
@@ -462,14 +462,14 @@ paths:
                     visible:
                       type: boolean
                       description: |
-                        top ページのカテゴリー一覧にて表示するか否か
+                        top ページのカテゴリー一覧にて表示するか否か  
                         通常、公開されているかどうかを示しています。
 
   /blog/revisions/:
     get:
       summary: revision のリストを取得
       description: |
-        admin の場合は 全 revision を取得できる
+        admin の場合は 全 revision を取得できる  
         writer の場合は revision の author と writer の ID が一致するもののみ取得できる
       tags:
       - blog revision
@@ -496,7 +496,7 @@ paths:
       responses:
         200:
           description: |
-            検索条件をすべて満たした revision の配列
+            検索条件をすべて満たした revision の配列  
             該当するものがない場合は空の配列
           content:
             application/json:
@@ -539,13 +539,13 @@ paths:
     post:
       summary: 寄稿を投稿する
       description: |
-        投稿された寄稿は「名もなき麻布生」名義で revision として作成される
+        投稿された寄稿は「名もなき麻布生」名義で revision として作成される  
         「名もなき麻布生」 は ID anonymous, password は空文字列のものを用意する
       tags:
       - blog revision
       requestBody:
         description: |
-          投稿したい寄稿の情報
+          投稿したい寄稿の情報  
           article_id: バックエンド側で重複しないように「contrib_(英数列5文字)」となるように設定する
         content:
           application/json:
@@ -601,7 +601,7 @@ paths:
     post:
       summary: revision を編集する
       description: |
-        指定された revision を元に新たに revision を作成する
+        指定された revision を元に新たに revision を作成する  
         指定された元の revision は更新されない
       tags:
       - blog revision
@@ -609,7 +609,7 @@ paths:
       - admin: []
       requestBody:
         description: |
-          更新したい情報
+          更新したい情報  
           指定されなかった要素がある場合は、元の revision と同一の内容になる
         content:
           application/json:
@@ -696,7 +696,7 @@ paths:
       responses:
         201:
           description: |
-            image の id
+            image の id  
             id: 自動生成のランダムな40文字の英数列
           content:
             application/json:
@@ -805,8 +805,8 @@ paths:
       responses:
         200:
           description: |
-            画像
-            title: `\n`または改行コードが含まれている場合改行される
+            画像  
+            title: `\n`または改行コードが含まれている場合改行される  
             author: article に handle_name が設定されている場合、 handle_name が代わりに表示される
           content:
             image/*:

From e789fb087751e23bd677df729734e1b6f36b559b Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Sun, 26 Jul 2020 12:53:34 +0900
Subject: [PATCH 18/34] docs: add / if necessary

Co-Authored-By: subaru <contact@su8ru.dev>
---
 swagger.yaml | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/swagger.yaml b/swagger.yaml
index 660de3b..bc00d84 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -7,7 +7,7 @@ servers:
 - url: http://localhost:8000/ # for local test
 
 paths:
-  /admin/login:
+  /admin/login/:
     post:
       summary: ログイン認証と API キーの受け取り
       description: 5回/分まで試行可能
@@ -49,7 +49,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-  /admin/user:
+  /admin/user/:
     get:
       summary: ログイン中の Admin の情報の取得
       description: Admin の API KEY から、アカウント情報を取得
@@ -78,7 +78,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-  /admin/change_password:
+  /admin/change_password/:
     post:
       summary: パスワード変更
       tags:
@@ -102,7 +102,7 @@ paths:
         400:
           description: 新しいパスワードが条件を満たしていない
 
-  /writer/login:
+  /writer/login/:
     post:
       summary: ログイン認証と API キーの受け取り
       tags:
@@ -143,7 +143,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-  /writer/user:
+  /writer/user/:
     get:
       summary: ログイン中の Writer の情報の取得
       description: Writer の API KEY から、アカウント情報を取得
@@ -172,7 +172,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-  /writer/change_password:
+  /writer/change_password/:
     post:
       summary: パスワード変更
       tags:
@@ -196,7 +196,7 @@ paths:
         400:
           description: 新しいパスワードが条件を満たしていない
 
-  /blog/articles:
+  /blog/articles/:
     get:
       summary: article のリストを取得
       tags:
@@ -357,7 +357,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-  /blog/articles/{id}/good:
+  /blog/articles/{id}/good/:
     parameters:
     - $ref: "#/components/parameters/blogArticleId"
     put:
@@ -398,7 +398,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-  /blog/articles/{id}/bad:
+  /blog/articles/{id}/bad/:
     parameters:
     - $ref: "#/components/parameters/blogArticleId"
     put:
@@ -628,7 +628,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-  /blog/revisions/{id}/accept:
+  /blog/revisions/{id}/accept/:
     parameters:
     - $ref: "#/components/parameters/blogRevisionId"
     patch:
@@ -651,7 +651,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-  /blog/revisions/{id}/reject:
+  /blog/revisions/{id}/reject/:
     parameters:
     - $ref: "#/components/parameters/blogRevisionId"
     patch:
@@ -674,7 +674,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
 
-  /images:
+  /images/:
     post:
       summary: 新しい imgae を投稿する
       tags:
@@ -713,7 +713,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-  /images/{id}:
+  /images/{id}/:
     get:
       summary: id から image を取得する
       description: |
@@ -764,7 +764,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
 
-  /ogimage:
+  /ogimage/:
     get:
       summary: 固定ページ用の ogimage を生成する
       tags:
@@ -825,7 +825,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-  /ogimage/preview:
+  /ogimage/preview/:
     get:
       summary: ogimage を指定されたパラメータから生成する
       tags:

From 2205451e81fcadcfd079830ee2c82a731e2c34b5 Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Sun, 26 Jul 2020 15:35:33 +0900
Subject: [PATCH 19/34] docs: fix with review comment

Co-Authored-By: subaru <contact@su8ru.dev>
---
 swagger.yaml | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/swagger.yaml b/swagger.yaml
index bc00d84..828498b 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -1,7 +1,7 @@
 openapi: 3.0.0
 info:
   version: 1.7.0
-  title: 73rd Afes website api
+  title: 73rd Afes website API
 servers:
 - url: https://api.afes.info/
 - url: http://localhost:8000/ # for local test
@@ -9,7 +9,7 @@ servers:
 paths:
   /admin/login/:
     post:
-      summary: ログイン認証と API キーの受け取り
+      summary: ログイン認証と Admin API token の受け取り
       description: 5回/分まで試行可能
       tags:
       - admin auth
@@ -29,7 +29,7 @@ paths:
                   type: string
       responses:
         200:
-          description: Admin api token
+          description: Admin API token
           content:
             application/json:
               schema:
@@ -51,15 +51,15 @@ paths:
                 $ref: "#/components/schemas/Error"
   /admin/user/:
     get:
-      summary: ログイン中の Admin の情報の取得
-      description: Admin の API KEY から、アカウント情報を取得
+      summary: ログイン中の admin の情報の取得
+      description: admin API token から、アカウント情報を取得
       tags:
       - admin auth
       security:
       - admin: []
       responses:
         200:
-          description: ログイン中の Admin ユーザー情報
+          description: ログイン中の admin ユーザー情報
           content:
             application/json:
               schema:
@@ -73,7 +73,7 @@ paths:
                   name:
                     type: string
         401:
-          description: Admin Token が無効
+          description: admin API Token が無効
           content:
             application/json:
               schema:
@@ -104,7 +104,7 @@ paths:
 
   /writer/login/:
     post:
-      summary: ログイン認証と API キーの受け取り
+      summary: ログイン認証と writer API token の受け取り
       tags:
       - writer auth
       requestBody:
@@ -123,7 +123,7 @@ paths:
                   type: string
       responses:
         200:
-          description: Admin api token
+          description: writer API token
           content:
             application/json:
               schema:
@@ -146,14 +146,14 @@ paths:
   /writer/user/:
     get:
       summary: ログイン中の Writer の情報の取得
-      description: Writer の API KEY から、アカウント情報を取得
+      description: Writer API token から、アカウント情報を取得
       tags:
       - writer auth
       security:
       - blogWriter: []
       responses:
         200:
-          description: ログイン中のAdminユーザー情報
+          description: ログイン中の writer ユーザー情報
           content:
             application/json:
               schema:
@@ -470,7 +470,7 @@ paths:
       summary: revision のリストを取得
       description: |
         admin の場合は 全 revision を取得できる  
-        writer の場合は revision の author と writer の ID が一致するもののみ取得できる
+        writer の場合は revision の author と writer が一致するもののみ取得できる
       tags:
       - blog revision
       security:
@@ -573,7 +573,7 @@ paths:
     - $ref: "#/components/parameters/blogRevisionId"
     get:
       summary: revision を取得する
-      description: writer の場合、user_id が一致していない revision は取得できない
+      description: writer の場合、 自身が author ではない revision は取得できない
       tags:
       - blog revision
       security:
@@ -772,7 +772,7 @@ paths:
       parameters:
       - in: query
         name: title
-        description: タイトル `\n`または改行コードで改行
+        description: タイトル `\n` または `%0A` で改行
         required: true
         schema:
           type: string
@@ -836,7 +836,7 @@ paths:
         required: true
         schema:
           type: string
-        description: title `\n`または改行コードで改行
+        description: title `\n` または `%0A` で改行
       - in: query
         name: author
         required: false

From fdb3fe3e3608d74cdb0dbd4020fa3fb219c3e404 Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Sun, 26 Jul 2020 18:36:32 +0900
Subject: [PATCH 20/34] docs: fix description in image/{id} orig

---
 swagger.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/swagger.yaml b/swagger.yaml
index 828498b..df35a00 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -748,7 +748,7 @@ paths:
         schema:
           type: string
           enum: ['yes']
-        description: オリジナルの画像を取得するかどうか
+        description: 指定した場合、オリジナルの画像が返ってくる
       responses:
         200:
           description: content

From 68f8ddd679b562792936ca916b07d1147683f660 Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Sun, 26 Jul 2020 18:37:52 +0900
Subject: [PATCH 21/34] docs: change title to CamelCase

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 2fd5e97..363954f 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# 73rd Afes website API documentation
+# 73rd Afes website API Documentation
 ![](https://img.shields.io/badge/dynamic/yaml?color=007ec6&label=version&style=for-the-badge&query=$.info.version&url=https://raw.githubusercontent.com/afes-website/docs/develop/swagger.yaml)
 
 ![Swagger](https://img.shields.io/badge/-Swagger-6d9a00.svg?logo=swagger&logoColor=fff&style=flat-square)

From 6bb4242b8d74d45421c3aeb3ce589c2c62eaa242 Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Sun, 26 Jul 2020 18:44:07 +0900
Subject: [PATCH 22/34] docs: translate in /writer/user get 401

---
 swagger.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/swagger.yaml b/swagger.yaml
index df35a00..b5ab64a 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -167,7 +167,7 @@ paths:
                   name:
                     type: string
         401:
-          description: Not logged in
+          description: writer API token が無効
           content:
             application/json:
               schema:

From 51bdf5b462bc2508b0ca90ad6ba6b0e0c61dfd3c Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Sun, 26 Jul 2020 18:56:45 +0900
Subject: [PATCH 23/34] fix: roll back the description in /image/{id}

---
 swagger.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/swagger.yaml b/swagger.yaml
index b5ab64a..c556d72 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -748,7 +748,7 @@ paths:
         schema:
           type: string
           enum: ['yes']
-        description: 指定した場合、オリジナルの画像が返ってくる
+        description: オリジナルの画像を取得するかどうか
       responses:
         200:
           description: content

From 691991296e47e42f1d033dddbb9547a74bd2fde3 Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Sun, 26 Jul 2020 19:03:54 +0900
Subject: [PATCH 24/34] docs: reword in components

---
 swagger.yaml | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/swagger.yaml b/swagger.yaml
index c556d72..7ca1996 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -948,11 +948,11 @@ components:
           readOnly: true
           enum: [waiting, accepted, rejected]
           description: >
-            * `waiting` - Waiting for acceptance
+            * `waiting` - admin の審査まちの状態
 
-            * `accepted` - Accepted and ready to be published
+            * `accepted` - 承認された状態 この状態の revision のみ公開できる
 
-            * `rejected` - Rejected and could not to be published
+            * `rejected` - 公開が拒否された状態
       required:
       - id
       - title
@@ -968,7 +968,7 @@ components:
       required: true
       schema:
         type: string
-      description: id of an article
+      description: article の ID
     blogRevisionId:
       in: path
       name: id
@@ -976,16 +976,16 @@ components:
       schema:
         type: integer
         format: int32
-      description: id of a revision
+      description: revision の ID
 
   securitySchemes:
     admin:
       type: apiKey
       in: header
       name: X-ADMIN-TOKEN
-      description: Credentials or access token for API
+      description: API token の情報
     blogWriter:
       type: apiKey
       in: header
       name: X-BLOG-WRITER-TOKEN
-      description: Credentials or access token for API
+      description: API token の情報

From 5a5613cb07ef39cf3a290dca154c9ea4a3bb6fe7 Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Sun, 26 Jul 2020 20:29:05 +0900
Subject: [PATCH 25/34] docs: change "id" to "ID"

---
 swagger.yaml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/swagger.yaml b/swagger.yaml
index 7ca1996..bd5a838 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -296,7 +296,7 @@ paths:
                   - updated_at
                   - content
         404:
-          description: id に該当する article が存在しない
+          description: ID に該当する article が存在しない
           content:
             application/json:
               schema:
@@ -696,7 +696,7 @@ paths:
       responses:
         201:
           description: |
-            image の id  
+            image の ID  
             id: 自動生成のランダムな40文字の英数列
           content:
             application/json:
@@ -715,7 +715,7 @@ paths:
                 $ref: "#/components/schemas/Error"
   /images/{id}/:
     get:
-      summary: id から image を取得する
+      summary: ID から image を取得する
       description: |
         original を指定すると、アップロードされた元ファイルの画像が取得される  
         幅・高さの両方を指定すると、縦横でそれぞれ拡大縮小をする  
@@ -729,7 +729,7 @@ paths:
         required: true
         schema:
           type: string
-        description: image の id
+        description: image の ID
       - in: query
         name: w
         required: false
@@ -801,7 +801,7 @@ paths:
         required: true
         schema:
           type: string
-        description: article の id
+        description: article の ID
       responses:
         200:
           description: |

From dc2832ed6c1715bb1670ca7a50d0cee3833522b8 Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Sun, 26 Jul 2020 21:31:31 +0900
Subject: [PATCH 26/34] fix: write ogimage-article title's description
 certainly

Co-Authored-By: subaru <contact@su8ru.dev>
---
 swagger.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/swagger.yaml b/swagger.yaml
index bd5a838..acb8d0c 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -806,7 +806,7 @@ paths:
         200:
           description: |
             画像  
-            title: `\n`または改行コードが含まれている場合改行される  
+            title: `\n` または `%0A` で改行
             author: article に handle_name が設定されている場合、 handle_name が代わりに表示される
           content:
             image/*:

From c5c16bd95982fcc50af37d0b8b90dfd00fd92b4b Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Sun, 26 Jul 2020 21:35:36 +0900
Subject: [PATCH 27/34] fix: change "Admin", "Writer" to "admin", "writer"

Co-Authored-By: subaru <contact@su8ru.dev>
---
 swagger.yaml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/swagger.yaml b/swagger.yaml
index acb8d0c..f0386bd 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -9,7 +9,7 @@ servers:
 paths:
   /admin/login/:
     post:
-      summary: ログイン認証と Admin API token の受け取り
+      summary: ログイン認証と admin API token の受け取り
       description: 5回/分まで試行可能
       tags:
       - admin auth
@@ -29,7 +29,7 @@ paths:
                   type: string
       responses:
         200:
-          description: Admin API token
+          description: admin API token
           content:
             application/json:
               schema:
@@ -145,8 +145,8 @@ paths:
                 $ref: "#/components/schemas/Error"
   /writer/user/:
     get:
-      summary: ログイン中の Writer の情報の取得
-      description: Writer API token から、アカウント情報を取得
+      summary: ログイン中の writer の情報の取得
+      description: writer API token から、アカウント情報を取得
       tags:
       - writer auth
       security:

From b996978b77ea8b9217f0991edaba0e94466e5825 Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Sun, 26 Jul 2020 21:37:37 +0900
Subject: [PATCH 28/34] =?UTF-8?q?docs:=20merge=20expression=20"=E5=AE=8C?=
 =?UTF-8?q?=E4=BA=86"=20to=20"=E6=88=90=E5=8A=9F"?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: subaru <contact@su8ru.dev>
---
 swagger.yaml | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/swagger.yaml b/swagger.yaml
index f0386bd..5ff8bc2 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -98,7 +98,7 @@ paths:
                   type: string
       responses:
         204:
-          description: 処理完了
+          description: 成功 返り値なし
         400:
           description: 新しいパスワードが条件を満たしていない
 
@@ -192,7 +192,7 @@ paths:
                   type: string
       responses:
         204:
-          description: 処理完了
+          description: 成功 返り値なし
         400:
           description: 新しいパスワードが条件を満たしていない
 
@@ -350,7 +350,7 @@ paths:
       - blog article
       responses:
         204:
-          description: 削除完了 返り値なし
+          description: 成功 返り値なし
         404:
           description: 指定された article が存在しない
           content:
@@ -524,7 +524,7 @@ paths:
               $ref: "#/components/schemas/BlogRevision"
       responses:
         201:
-          description: 完了
+          description: revision の情報
           content:
             application/json:
               schema:
@@ -557,7 +557,7 @@ paths:
                     readOnly: true
       responses:
         201:
-          description: 投稿完了
+          description: revision の情報
           content:
             application/json:
               schema:
@@ -662,7 +662,7 @@ paths:
       - blog revision
       responses:
         200:
-          description: 成功
+          description: 成功 返り値なし
           content:
             application/json:
               schema:
@@ -948,7 +948,7 @@ components:
           readOnly: true
           enum: [waiting, accepted, rejected]
           description: >
-            * `waiting` - admin の審査まちの状態
+            * `waiting` - admin の審査待ちの状態
 
             * `accepted` - 承認された状態 この状態の revision のみ公開できる
 

From ad11e1afb294809c5f754d6ce75c2ec5413f151e Mon Sep 17 00:00:00 2001
From: Takeno-hito <18237819+Takeno-hito@users.noreply.github.com>
Date: Sun, 26 Jul 2020 21:38:46 +0900
Subject: [PATCH 29/34] docs: translate revision/id/accept/, that I forgot

Co-Authored-By: subaru <contact@su8ru.dev>
---
 swagger.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/swagger.yaml b/swagger.yaml
index 5ff8bc2..81e3dea 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -646,7 +646,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/BlogRevision"
         404:
-          description: no specified revision found
+          description: 該当する revision が存在しない
           content:
             application/json:
               schema:

From a861aa651bd34571199b4c480427e51faf4c6941 Mon Sep 17 00:00:00 2001
From: subaru <s@su8ru.dev>
Date: Sun, 26 Jul 2020 22:11:58 +0900
Subject: [PATCH 30/34] =?UTF-8?q?fix:=20=E3=81=8C=20->=20=E3=81=8B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 swagger.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/swagger.yaml b/swagger.yaml
index 81e3dea..34d5dee 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -708,7 +708,7 @@ paths:
                 required:
                 - id
         400:
-          description: パラメータに問題があるが、アップロードされたものが画像でない
+          description: パラメータに問題があるか、アップロードされたものが画像でない
           content:
             application/json:
               schema:

From 92bcdbc9ac092895115717fa3853601acb12e715 Mon Sep 17 00:00:00 2001
From: subaru <s@su8ru.dev>
Date: Sun, 26 Jul 2020 22:12:19 +0900
Subject: [PATCH 31/34] fix: original -> orig

---
 swagger.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/swagger.yaml b/swagger.yaml
index 34d5dee..972eda2 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -717,7 +717,7 @@ paths:
     get:
       summary: ID から image を取得する
       description: |
-        original を指定すると、アップロードされた元ファイルの画像が取得される  
+        orig を指定すると、アップロードされた元サイズの画像が取得される  
         幅・高さの両方を指定すると、縦横でそれぞれ拡大縮小をする  
         幅・高さの片方を指定すると、画像全体を適切に拡大縮小する  
         すべて指定しない場合は、縦幅が最大600、横幅が最大1080になるように設定される  

From 74772f5796e996bc0bed8f81e260f2978ec35100 Mon Sep 17 00:00:00 2001
From: subaru <s@su8ru.dev>
Date: Sun, 26 Jul 2020 22:13:31 +0900
Subject: [PATCH 32/34] fix: separate title and author

---
 swagger.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/swagger.yaml b/swagger.yaml
index 972eda2..03dddfd 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -806,7 +806,7 @@ paths:
         200:
           description: |
             画像  
-            title: `\n` または `%0A` で改行
+            title: `\n` または `%0A` で改行  
             author: article に handle_name が設定されている場合、 handle_name が代わりに表示される
           content:
             image/*:

From 81b2887da7370f05e35041521876f65b15587151 Mon Sep 17 00:00:00 2001
From: subaru <s@su8ru.dev>
Date: Sun, 26 Jul 2020 22:15:35 +0900
Subject: [PATCH 33/34] fix: status description

---
 swagger.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/swagger.yaml b/swagger.yaml
index 03dddfd..c48a45c 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -948,11 +948,11 @@ components:
           readOnly: true
           enum: [waiting, accepted, rejected]
           description: >
-            * `waiting` - admin の審査待ちの状態
+            * `waiting` - admin の審査待ち
 
-            * `accepted` - 承認された状態 この状態の revision のみ公開できる
+            * `accepted` - 承認済 この状態の revision のみ公開可能
 
-            * `rejected` - 公開が拒否された状態
+            * `rejected` - 却下済
       required:
       - id
       - title

From bfea3bd46f2941fa9be6e3d17eec0bea535bc299 Mon Sep 17 00:00:00 2001
From: subaru <s@su8ru.dev>
Date: Sun, 26 Jul 2020 22:19:11 +0900
Subject: [PATCH 34/34] fix: typo imgae -> image

---
 swagger.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/swagger.yaml b/swagger.yaml
index c48a45c..e490fc0 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -676,7 +676,7 @@ paths:
 
   /images/:
     post:
-      summary: 新しい imgae を投稿する
+      summary: 新しい image を投稿する
       tags:
       - images
       security: