Merge pull request #5 from kitcc-org/4-openapi

APIの仕様書を作成した

.github/workflows/publish_spec.yml

@@ -0,0 +1,28 @@
+name: Publish API Specification
+
+on:
+  pull_request:
+    branches:
+      - main
+    types:
+      - closed
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Generate Swagger UI
+        uses: Legion2/swagger-ui-action@v1
+        with:
+          output: swagger-ui
+          spec-file: ./api/openapi.yaml
+
+      - name: Publish to Cloudflare Pages
+        uses: cloudflare/pages-action@v1
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          projectName: kitcc-library-api-doc
+          directory: swagger-ui
+          branch: main

.github/workflows/validate_spec.yml

@@ -0,0 +1,22 @@
+name: Validate API Specification
+
+on:
+  push:
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install redocly-cli
+        run: |
+          npm install @redocly/cli -g
+
+      - name: Validate API Specification
+        run: |
+          redocly lint ./api/openapi.yml

api/.gitignore

@@ -0,0 +1 @@
+bundle.yml

api/README.md

@@ -0,0 +1,24 @@
+## ディレクトリ構造
+```
+api
+├── bundle.yml ... APIに仕様を1つにまとめたYAMLファイル
+├── components ... 使い回すために部品化された仕様
+│   ├── examples
+│   ├── responses
+│   └── schemas
+├── openapi.yml ... エントリーポイント
+├── paths       ... 利用可能なエンドポイントとメソッド
+└── redocly.yml ... redocly-cliの設定ファイル
+```
+
+## CLI
+
+バリデーション
+```
+$ npm run lint
+```
+
+APIの仕様を1つのYAMLファイルにまとめる
+```
+$ npm run bundle
+```

api/components/examples/book.yml

@@ -0,0 +1,11 @@
+value:
+  id: 1
+  title: "計算機プログラムの構造と解釈"
+  author:
+    - "Harold Abelson"
+    - "Gerald Jay Sussman"
+    - "Julie Sussman"
+  publisher: "翔泳社"
+  thumbnail: "http://books.google.com/books/content?id=LlH-oAEACAAJ&printsec=frontcover&img=1&zoom=1&source=gbs_api"
+  isbn: "9784798135984"
+  stock: 1

api/components/examples/user.yml

@@ -0,0 +1,5 @@
+value:
+  id: 1
+  name: "比企谷八幡"
+  email: "hikigaya@oregairu.com"
+  passwordDigest: "d41d8cd98f00b204e9800998ecf8427e"

api/components/responses/4xx.yml

@@ -0,0 +1,29 @@
+BadRequest:
+  description: リクエストの構文が誤っている
+  content:
+    application/json:
+      schema:
+        $ref: "../schemas/response.yml"
+      example:
+        code: 400
+        message: "Bad Request"
+
+Unauthorized:
+  description: 適切な認証情報を持たずにリソースにアクセスしようとした
+  content:
+    application/json:
+      schema:
+        $ref: "../schemas/response.yml"
+      example:
+        code: 401
+        message: "Unauthorized"
+
+NotFound:
+  description: 指定されたリソースが存在しない
+  content:
+    application/json:
+      schema:
+        $ref: "../schemas/response.yml"
+      example:
+        code: 404
+        message: "Not Found"

api/components/responses/5xx.yml

@@ -0,0 +1,9 @@
+InternalServerError:
+  description: サーバ内部でエラーが発生した
+  content:
+    application/json:
+      schema:
+        $ref: "../schemas/response.yml"
+      example:
+        code: 500
+        message: "Internal Server Error"

api/components/schemas/book.yml

@@ -0,0 +1,27 @@
+
+type: object
+properties:
+  id:
+    type: integer
+  title:
+    type: string
+  author:
+    type: array
+    items:
+      type: string
+  publisher:
+    type: string
+  thumbnail:
+    type: string
+  isbn:
+    type: string
+    pattern: '^\d{13}$'
+  stock:
+    type: integer
+required:
+  - id
+  - title
+  - author
+  - publisher
+  - isbn
+  - stock

api/components/schemas/loan.yml

@@ -0,0 +1,16 @@
+type: object
+properties:
+  id:
+    type: integer
+  userId:
+    type: integer
+  bookId:
+    type: integer
+  volume:
+    type: integer
+  createdAt:
+    type: string
+    format: date-time
+  updatedAt:
+    type: string
+    format: date-time

api/components/schemas/response.yml

@@ -0,0 +1,9 @@
+type: object
+properties:
+  code:
+    type: integer
+  message:
+    type: string
+required:
+  - code
+  - message

api/components/schemas/user.yml

@@ -0,0 +1,16 @@
+
+type: object
+properties:
+  id:
+    type: integer
+  name:
+    type: string
+  email:
+    type: string
+    format: email
+  passwordDigest:
+    type: string
+required:
+  - id
+  - name
+  - email

api/openapi.yml

@@ -0,0 +1,59 @@
+openapi: 3.0.3
+info:
+  title: KITCC Library API
+  contact:
+    name: KITCC
+    url: "https://www.kitcc.org/"
+    email: "question@kitcc.org"
+  license: 
+    name: MIT
+    url: https://en.wikipedia.org/wiki/MIT_License
+  version: "1.0.0"
+
+servers:
+  - url: "https://kitcc-library.kitcc.workers.dev"
+
+tags:
+  - name: book
+    description: 書籍に関するAPI
+  - name: user
+    description: ユーザーに関するAPI
+  - name: loan
+    description: 貸借に関するAPI
+  - name: auth
+    description: 認証に関するAPI
+
+paths:
+  /books:
+    $ref: "./paths/book.yml#/books"
+  /books/{bookId}:
+    $ref: "./paths/book.yml#/book"
+  /books/search:
+    $ref: "paths/book.yml#/search"
+
+  /users:
+    $ref: "./paths/user.yml#/users"
+  /users/{userId}:
+    $ref: "paths/user.yml#/user"
+
+  /loans:
+    $ref: "./paths/loan.yml#/loans"
+
+  /login:
+    $ref: "./paths/auth.yml#/login"
+  /logout:
+    $ref: "paths/auth.yml#/logout"
+
+components:
+  securitySchemes:
+    BasicAuth:
+      type: http
+      scheme: basic
+
+  schemas:
+    Book:
+      $ref: "./components/schemas/book.yml"
+    User:
+      $ref: "./components/schemas/user.yml"
+    Loan:
+      $ref: "./components/schemas/loan.yml"

api/package.json

@@ -0,0 +1,6 @@
+{
+  "scripts": {
+    "lint": "npx @redocly/cli lint openapi.yml",
+    "bundle": "npx @redocly/cli bundle openapi.yml --output bundle.yml"
+  }
+}

api/paths/auth.yml

@@ -0,0 +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"
+            examples:
+              user:
+                $ref: "../components/examples/user.yml"
+      '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"