全体的なプロジェクトの整理

.github/workflows/check.yml

@@ -25,8 +25,8 @@ jobs:
       - name: install dependencies
         run: pnpm install
       - name: check formatting
-        run: pnpm lint:prettier
+        run: pnpm check:format
       - name: build
         run: pnpm build:tsp
       - name: lint openapi
-        run: pnpm lint:redocly
+        run: pnpm check:lint

.prettierrc.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json.schemastore.org/prettierrc",
+
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "trailingComma": "es5",
+  "semi": false,
+  "singleQuote": false,
+
+  "plugins": ["@typespec/prettier-plugin-typespec"],
+  "overrides": [
+    {
+      "files": "*.tsp",
+      "options": { "parser": "typespec" }
+    }
+  ]
+}

README.md

@@ -1,5 +1,12 @@
 # ODPT OpenAPI
 
+OpenAPI specification of ODPT API
+
+## About ODPT API
+
+- [Official Document](https://developer.odpt.org/documents)
+- [Datasets](https://ckan.odpt.org/dataset)
+
 ## Development
 
 ### Requirements
@@ -15,16 +22,23 @@
 pnpm i
 ```
 
-2. Start Typespec watcher and documentation server from openapi
+2. (Optional) Install VSCode Extension
 
-selectedAPIName is the name of `openapi.${selectedAPIName}.yaml`
+```bash
+pnpm tsp code install
+```
+
+3. Start TypeSpec watcher and Document server
 
 ```bash
-NAME=${selectedAPIName} pnpm dev
+pnpm dev
 ```
 
+Document page will be available at [`http://127.0.0.1:8080`](http://127.0.0.1:8080)
+
 ### Scripts
 
-- `pnpm dev` - 2. Start Typespec watcher and documentation server from openapi
-- `pnpm build` - Build the tsp files
-- `pnpm lint` - Lint the tsp files and openapi files
+- `pnpm dev`: Run TypeSpec watcher and Document Server
+- `pnpm build`: Compile TypeSpec and Build document page
+- `pnpm check`: Check TypeSpec format and OpenAPI lint
+- `pnpm fix`: Fix TypeSpec format

package.json

@@ -1,19 +1,20 @@
 {
   "name": "odpt-openapi",
-  "version": "0.1.0",
+  "version": "1.0.1",
   "type": "module",
   "scripts": {
-    "dev": "pnpm dev:tsp & pnpm dev:docs",
-    "dev:tsp": "pnpm build:tsp --watch",
-    "dev:docs": "redocly preview-docs ./dist/@typespec/openapi3/openapi.$NAME.yaml",
-    "build": "pnpm build:tsp && pnpm build:docs",
-    "build:tsp": "tsp compile ./src --output-dir ./dist",
-    "build:docs": "redocly build-docs -o ./dist/doc/index.html",
-    "lint": "pnpm /^lint:.*/",
-    "lint:prettier": "pnpm run:prettier . --check",
-    "lint:redocly": "redocly lint ./dist/@typespec/openapi3/openapi.*.yaml",
-    "typecheck": "pnpm build:tsp --noEmit",
-    "run:prettier": "prettier --ignore-unknown --no-error-on-unmatched-pattern --cache"
+    "dev": "pnpm /^watch:.*/",
+    "watch:tsp": "tsp compile ./src/ --watch",
+    "watch:redocly": "redocly preview-docs",
+    "build": "pnpm build:tsp && pnpm build:redocly",
+    "build:tsp": "tsp compile ./src/",
+    "build:redocly": "redocly build-docs -o './dist/docs/index.html'",
+    "prebuild": "pnpx rimraf ./dist",
+    "check": "pnpm /^check:.*/",
+    "check:format": "prettier -c ./src/",
+    "check:lint": "redocly lint",
+    "fix": "pnpm /^fix:.*/",
+    "fix:format": "prettier -w ./src/"
   },
   "peerDependencies": {
     "@typespec/compiler": "0.61.0",
@@ -25,10 +26,10 @@
     "@redocly/cli": "^1.25.8",
     "@typespec/compiler": "0.61.0",
     "@typespec/http": "0.61.0",
+    "@typespec/openapi": "0.61.0",
     "@typespec/openapi3": "0.61.0",
     "@typespec/prettier-plugin-typespec": "^0.61.0",
     "@typespec/rest": "0.61.0",
     "prettier": "^3.3.3"
-  },
-  "private": true
+  }
 }

redocly.yaml

@@ -0,0 +1,6 @@
+extends:
+  - recommended
+
+apis:
+  odpt@v4:
+    root: ./dist/openapi/openapi.yaml

src/common/class.tsp

@@ -1,14 +1,8 @@
-import "@typespec/http";
-
-import "./error.tsp";
-
-using TypeSpec.Http;
-
 @doc("アクセストークン")
 scalar ConsumerKey extends string;
 
 @doc("固有識別子")
-scalar URN extends string;
+scalar `odpt.urn` extends string;
 
 @doc("固有識別子の別名 多くが`odpt.hoge:fuga`形式")
 scalar `odpt.url` extends string;
@@ -39,7 +33,7 @@ model Calendar {
   `@context`: url;
 
   @doc("固有識別子(ucode)")
-  `@id`: URN;
+  `@id`: `odpt.urn`;
 
   @doc("クラス指定")
   `@type`: "odpt:Calendar";
@@ -50,10 +44,10 @@ model Calendar {
   @doc("固有識別子")
   `owl:sameAs`: url;
 
-  @doc("カレンダー名称（日本語）")
+  @doc("カレンダー名称(日本語)")
   `dc:title`?: string;
 
-  @doc("カレンダー名称（多言語対応）")
+  @doc("カレンダー名称(多言語対応)")
   `odpt:calendarTitle`?: MultilingualTitle;
 }
 
@@ -64,7 +58,7 @@ model Operator {
   `@context`: url;
 
   @doc("固有識別子(ucode)")
-  `@id`: URN;
+  `@id`: `odpt.urn`;
 
   @doc("クラス指定")
   `@type`: "odpt:Operator";
@@ -75,31 +69,9 @@ model Operator {
   @doc("固有識別子")
   `owl:sameAs`: url;
 
-  @doc("事業者名称（日本語）")
+  @doc("事業者名称(日本語)")
   `dc:title`?: string;
 
-  @doc("事業者名称（多言語対応）")
+  @doc("事業者名称(多言語対応)")
   `odpt:operatorTitle`?: MultilingualTitle;
 }
-
-@route("/api/v4/odpt/Calendar")
-interface CalendarOperations {
-  @doc("曜日・日付区分(odpt:Calendar)の内容を取得する")
-  @get
-  getCalendars(
-    @query @doc("開発者サイトにて提供されるアクセストークン") `acl:consumerKey`: ConsumerKey,
-    @query @doc("データに付与された固有識別子") `@id`?: URN,
-    @query @doc("データに付与された固有識別子の別名") `owl:sameAs`?: url,
-  ): Calendar[] | Common.Error;
-}
-
-@route("/api/v4/odpt/Operator")
-interface OperatorOperations {
-  @doc("公共交通機関の事業者(odpt:Operator)の内容を取得する")
-  @get
-  getOperators(
-    @query @doc("開発者サイトにて提供されるアクセストークン") `acl:consumerKey`: ConsumerKey,
-    @query @doc("データに付与された固有識別子") `@id`?: URN,
-    @query @doc("データに付与された固有識別子の別名") `owl:sameAs`?: url,
-  ): Operator[] | Common.Error;
-}

src/main.tsp

@@ -1,12 +1,23 @@
 import "@typespec/http";
-import "@typespec/rest";
-import "@typespec/openapi3";
+import "@typespec/openapi";
+import "./routes/index.tsp";
 
-import "./common/error.tsp";
-import "./common/class.tsp";
+using TypeSpec.Http;
+using TypeSpec.OpenAPI;
 
-import "./search/index.tsp";
-import "./airplane/index.tsp";
-import "./train/index.tsp";
-import "./bus/index.tsp";
-import "./file/index.tsp";
+@service({
+  title: "ODPT API",
+})
+@server("https://api.odpt.org/api/v4", "公共交通のオープンデータ API")
+@server(
+  "https://api-challenge2024.odpt.org/api/v4",
+  "公共交通のオープンデータ API (チャレンジ2024専用)"
+)
+@info({
+  license: {
+    name: "公共交通オープンデータ基本ライセンス, 公共交通オープンデータチャレンジ限定ライセンス",
+    url: "https://developer.odpt.org/terms",
+  },
+})
+@useAuth(ApiKeyAuth<ApiKeyLocation.query, "acl:consumerKey">)
+namespace OdptAPI;