Define auth API (#4)

api/components/examples/user.yml

@@ -1,10 +1,12 @@
 request:
   value:
     name: "比企谷八幡"
+    email: "hikigaya@oregairu.com"
     password: "password"
 
 response:
   value:
     id: 1
     name: "比企谷八幡"
+    email: "hikigaya@oregairu.com"
     passwordDigest: "d41d8cd98f00b204e9800998ecf8427e"

api/components/schemas/user.yml

@@ -3,11 +3,15 @@ request:
   properties:
     name:
       type: string
+    email:
+      type: string
+      format: email
     password:
       type: string
       format: password
   required:
     - name
+    - email
     - password
 
 response:
@@ -17,8 +21,12 @@ response:
       type: integer
     name:
       type: string
+    email:
+      type: string
+      format: email
     passwordDigest:
       type: string
   required:
     - id
     - name
+    - email

api/openapi.yml

@@ -20,6 +20,8 @@ tags:
     description: ユーザーに関するAPI
   - name: loan
     description: 貸借に関するAPI
+  - name: auth
+    description: 認証に関するAPI
 
 paths:
   /books:
@@ -35,8 +37,10 @@ paths:
   # /loans:
   # /loans/{loanId}:
 
-  # /login:
-  # /logout:
+  /login:
+    $ref: "./paths/auth.yml#/login"
+  /logout:
+    $ref: "paths/auth.yml#/logout"
 
 components:
   securitySchemes:

api/paths/auth.yml

@@ -1,2 +1,72 @@
 login:
-
+  post:
+    tags:
+      - auth
+    operationId: login
+    summary: ログインする
+    description: セッションIDをCookieに保存する
+    security: []
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              email:
+                type: string
+                format: email
+              password:
+                type: string
+                format: password
+          example:
+            email: "username@example.com"
+            password: "password"
+    responses:
+      '200':
+        description: >
+          ログインに成功した．
+          `session_token`という名前のCookieにセッションIDが保存される．
+          以降のリクエストにはこのCookieを含める必要がある．
+        headers:
+          Set-Cookie:
+            schema:
+              type: string
+              example: session_token=abcde12345; Path=/; HttpOnly
+        content:
+          application/json:
+            schema:
+              $ref: "../components/schemas/user.yml#/response"
+            examples:
+              user:
+                $ref: "../components/examples/user.yml#/response"
+      '500':
+        $ref: "../components/responses/5xx.yml#/InternalServerError"
+
+logout:
+  delete:
+    tags:
+      - auth
+    operationId: logout
+    summary: ログアウトする
+    description: CookieからセッションIDを削除する
+    security: []
+    responses:
+      '204':
+        description: ログアウトに成功した
+        headers:
+          Set-Cookie:
+            schema:
+              type: string
+              example: session_token=; Path=/; Max-Age=0
+        content:
+          application/json:
+            schema:
+              $ref: "../components/schemas/response.yml"
+            example:
+              code: 204
+              message: "No Content"
+      '401':
+        $ref: "../components/responses/4xx.yml#/Unauthorized"
+      '500':
+        $ref: "../components/responses/5xx.yml#/InternalServerError"