API 定義を TypeSpec に置き換える

.github/workflows/compile-typespec-and-deploy.yml

@@ -0,0 +1,59 @@
+name: typespec-compile-and-deploy-gh-pages
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  compile:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install typespec
+        run: npm install -g @typespec/compiler
+
+      - name: Cache npm modules
+        uses: actions/cache@v4
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      - name: Install node_modules
+        run: npm ci
+
+      - name: Compile typespec
+        run: tsp compile .
+
+      - name: Install redocly-cli
+        uses: ./.github/actions/install-redocly-cli
+
+      - name: Build docs
+        run: redocly build-docs tsp-output/@typespec/openapi3/openapi.yaml -o ./docs/index.html -t ./.github/template.hbs
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs
+
+  deploy-github-pages:
+    needs: compile
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/lint-openapi.yml

@@ -1,29 +1,32 @@
-name: Lint OpenAPI
+name: Lint Typespec OpenAPI Definitions
 on:
-  pull_request:
-    branches:
-      - main
-  workflow_call:
+  push:
+
 jobs:
-  lint-definitions:
-    name: Lint OpenAPI definitions
-    runs-on: ubuntu-latest
+  check-format:
+    runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v4
-      - name: Install redocly-cli
-        uses: ./.github/actions/install-redocly-cli
-      - name: Lint OpenAPI yml
-        run: redocly lint ./schema/openapi.yml
-  lint-examples:
-    name: Lint OpenAPI examples
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - name: Install redocly-cli
-        uses: ./.github/actions/install-redocly-cli
-      - name: Bundle OpenAPI yml
-        run: redocly bundle ./schema/openapi.yml -o ./bundled-openapi.yml
-      - name: Install openapi-examples-validator
-        run: npm install -g openapi-examples-validator
-      - name: Lint examples
-        run: openapi-examples-validator ./bundled-openapi.yml
+      - name: checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install typespec
+        run: npm install -g @typespec/compiler
+
+      - name: Cache npm modules
+        uses: actions/cache@v4
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      - name: Install node_modules
+        run: npm ci
+
+      - name: Check format
+        run: tsp format --check "**/*.tsp"

.gitignore

@@ -1,2 +1,3 @@
 .idea
-docs
+node_modules
+**/tsp-output

README.md

@@ -4,27 +4,10 @@
 
 プロジェクトの目的やフロントエンド・バックエンドなどの関連リポジトリについては、[こちらのリポジトリ](https://github.com/GiganticMinecraft/seichi-portal)を参照してください。
 
-## 実装について
+## API 定義について
 
-スキーマは、[OpenAPI v3.0.3](https://spec.openapis.org/oas/v3.0.3)で記載されています。
-
-[GitHub Pages上に公開](https://giganticminecraft.github.io/seichi-api-schema/)もされており、視覚的に確認できるようになっています。これは`main`ブランチに更新があると、自動的にGitHub Actionsによって反映されます。
-
-### スキーマの構造
-
-```tree
-├── openapi.yml: 大元のファイル。ここでそれぞれのエンドポイントを指定している。
-└── paths: 各エンドポイントごとにディレクトリも区切っている。
-    ├── forms: フォームに関連するもの
-    │   ├── eachForm.yml: フォームIDを指定して操作するもの
-    │   ├── index.yml: フォームIDを指定しないで操作するもの
-    │   └── types: 各スキーマで再利用できる型をまとめている
-    │       ├── ...
-    ├── healthCheck: サーバーが起動しているかを確認する
-    │   └── index.yml
-    └── reCaptcha: Google reCaptchaの認証に使用する
-        └── index.yml
-```
+API の定義には [TypeSpec](https://typespec.io/) を使用しています。
+TypeSpec については[公式ドキュメント](https://typespec.io/docs)を参照してください。
 
 ### ローカルで確認する
 
@@ -34,12 +17,12 @@
 
 それぞれの違いは以下の通りです。
 
-* 8081
-  * Swaggerが提供するイメージを利用するコンテナです。
-  * バックエンドサーバーが起動していれば、画面から実際にバックエンドに向けてリクエストを送信することができます。
-* 8082
-  * redoclyが提供するイメージを利用するコンテナです。
-  * Swaggerのものに比べて、見やすくなっています。
+- 8081
+  - Swaggerが提供するイメージを利用するコンテナです。
+  - バックエンドサーバーが起動していれば、画面から実際にバックエンドに向けてリクエストを送信することができます。
+- 8082
+  - redoclyが提供するイメージを利用するコンテナです。
+  - Swaggerのものに比べて、見やすくなっています。
 
 ## ライセンス
 

compose.yaml

@@ -5,9 +5,9 @@ services:
     ports:
       - 127.0.0.1:8081:8080
     volumes:
-      - ./schema:/schema
+      - ./tsp-output/@typespec/openapi3:/schema
     environment:
-      SWAGGER_JSON: /schema/openapi.yml
+      SWAGGER_JSON: /schema/openapi.yaml
     restart: always
   redocly:
     build:
@@ -17,8 +17,8 @@ services:
     ports:
       - 127.0.0.1:8082:8080
     volumes:
-      - ./schema:/schema
+      - ./tsp-output/@typespec/openapi3:/schema
     environment:
-      SPEC_URL: /schema/openapi.yml
+      SPEC_URL: /schema/openapi.yaml
     restart: always
     init: true

docker/Dockerfile

@@ -6,7 +6,7 @@ ENV PORT=8080
 
 EXPOSE 8080
 
-RUN npm install -g @redocly/cli http-server
+RUN npm install -g @typespec/compiler @redocly/cli http-server 
 
 USER node
 WORKDIR /tmp/files

docker/entrypoint.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
 
-redocly build-docs /schema/openapi.yml -o ./docs/index.html -t ./template.hbs
+tsp compile .
+
+redocly build-docs ./tsp-output/@typespec/openapi3/openapi.yaml -o ./docs/index.html -t ./template.hbs
 http-server ./docs -p $PORT