From 25f818a3d6ff313783f9cff9a6fc7617e7d55788 Mon Sep 17 00:00:00 2001 From: marihachi Date: Sun, 15 Sep 2024 22:04:58 +0900 Subject: [PATCH] =?UTF-8?q?Spec:=20=E3=83=9A=E3=83=BC=E3=82=B8=E3=83=8D?= =?UTF-8?q?=E3=83=BC=E3=82=B7=E3=83=A7=E3=83=B3=E3=81=AE=E5=A4=89=E6=9B=B4?= =?UTF-8?q?=20(#137)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- spec/docs/api-reference-v1.md | 31 ++++---- spec/generated/openapi.yaml | 131 +++++++++++++++++----------------- spec/generated/schema.d.ts | 65 ++++++++++------- spec/src/api/v1/models.tsp | 37 +++++----- 4 files changed, 141 insertions(+), 123 deletions(-) diff --git a/spec/docs/api-reference-v1.md b/spec/docs/api-reference-v1.md index 5df3437..c323231 100644 --- a/spec/docs/api-reference-v1.md +++ b/spec/docs/api-reference-v1.md @@ -48,11 +48,11 @@ GET /api/v1/user/getUser GET /api/v1/user/searchUsers ``` ユーザー情報を検索する。\ -レスポンスヘッダーから結果の続きを取得するためのX-Next-CursorとX-Prev-Cursorが返される。 +レスポンスヘッダーに結果の続きを取得するための`X-Offset`が付加される。 ### query string -- nextCursor (optional) -- prevCursor (optional) +- offset (optional) +- limit (optional) @@ -72,12 +72,12 @@ POST /api/v1/user/deleteUser GET /api/v1/user/getFollowings ``` 指定したユーザーのフォロー一覧を取得する。\ -レスポンスヘッダーから結果の続きを取得するためのX-Next-CursorとX-Prev-Cursorが返される。 +レスポンスヘッダーに結果の続きを取得するための`X-Offset`が付加される。 ### query string - userId -- nextCursor (optional) -- prevCursor (optional) +- offset (optional) +- limit (optional) @@ -108,12 +108,12 @@ POST /api/v1/user/unfollowUser GET /api/v1/user/getHomeTimeline ``` ホームタイムラインを取得する。\ -レスポンスヘッダーから結果の続きを取得するためのX-Next-CursorとX-Prev-Cursorが返される。 +レスポンスヘッダーに結果の続きを取得するための`X-Next-Cursor`と`X-Prev-Cursor`が付加される。 ### query string - nextCursor (optional) - prevCursor (optional) - +- limit (optional) # leaf ネームスペース @@ -145,11 +145,11 @@ GET /api/v1/leaf/getLeaf GET /api/v1/leaf/searchLeafs ``` リーフを検索する。\ -レスポンスヘッダーから結果の続きを取得するためのX-Next-CursorとX-Prev-Cursorが返される。 +レスポンスヘッダーに結果の続きを取得するための`X-Offset`が付加される。 ### query string -- nextCursor (optional) -- prevCursor (optional) +- offset (optional) +- limit (optional) @@ -194,11 +194,11 @@ GET /api/v1/chatroom/getChatroom GET /api/v1/chatroom/searchChatrooms ``` チャットルームを検索する。\ -レスポンスヘッダーから結果の続きを取得するためのX-Next-CursorとX-Prev-Cursorが返される。 +レスポンスヘッダーに結果の続きを取得するための`X-Offset`が付加される。 ### query string -- nextCursor (optional) -- prevCursor (optional) +- offset (optional) +- limit (optional) @@ -231,9 +231,10 @@ GET /api/v1/chatroom/getTimeline ``` チャットルームのタイムラインを取得する。\ リーフの取得や削除、検索に関してはleafネームスペースのAPIを利用する。\ -レスポンスヘッダーでnextCursorとprevCursorが返される。 +レスポンスヘッダーに結果の続きを取得するための`X-Next-Cursor`と`X-Prev-Cursor`が付加される。 ### query string - chatroomId - nextCursor (optional) - prevCursor (optional) +- limit (optional) diff --git a/spec/generated/openapi.yaml b/spec/generated/openapi.yaml index 32674b9..f922375 100644 --- a/spec/generated/openapi.yaml +++ b/spec/generated/openapi.yaml @@ -123,8 +123,9 @@ paths: - Leaf operationId: ChatRoomApi_GetTimeline parameters: - - $ref: '#/components/parameters/Api.v1.GetChatRoomTimelineQueryString.nextCursor' - - $ref: '#/components/parameters/Api.v1.GetChatRoomTimelineQueryString.prevCursor' + - $ref: '#/components/parameters/Api.v1.CursorControl.nextCursor' + - $ref: '#/components/parameters/Api.v1.CursorControl.prevCursor' + - $ref: '#/components/parameters/Api.v1.CursorControl.limit' responses: '200': description: The request has succeeded. @@ -140,8 +141,8 @@ paths: - ChatRoom operationId: ChatRoomApi_SearchChatRooms parameters: - - $ref: '#/components/parameters/Api.v1.SearchChatRoomsQueryString.nextCursor' - - $ref: '#/components/parameters/Api.v1.SearchChatRoomsQueryString.prevCursor' + - $ref: '#/components/parameters/Api.v1.OffsetControl.offset' + - $ref: '#/components/parameters/Api.v1.OffsetControl.limit' responses: '200': description: The request has succeeded. @@ -252,8 +253,8 @@ paths: - Leaf operationId: LeafApi_SearchLeafs parameters: - - $ref: '#/components/parameters/Api.v1.SearchLeafsQueryString.nextCursor' - - $ref: '#/components/parameters/Api.v1.SearchLeafsQueryString.prevCursor' + - $ref: '#/components/parameters/Api.v1.OffsetControl.offset' + - $ref: '#/components/parameters/Api.v1.OffsetControl.limit' responses: '200': description: The request has succeeded. @@ -299,9 +300,9 @@ paths: - User operationId: UserApi_GetFollowings parameters: + - $ref: '#/components/parameters/Api.v1.OffsetControl.offset' + - $ref: '#/components/parameters/Api.v1.OffsetControl.limit' - $ref: '#/components/parameters/Api.v1.GetFollowingsQueryString.userId' - - $ref: '#/components/parameters/Api.v1.GetFollowingsQueryString.nextCursor' - - $ref: '#/components/parameters/Api.v1.GetFollowingsQueryString.prevCursor' responses: '200': description: The request has succeeded. @@ -318,8 +319,9 @@ paths: - Leaf operationId: UserApi_GetHomeTimeline parameters: - - $ref: '#/components/parameters/Api.v1.GetHomeTimelineQueryString.nextCursor' - - $ref: '#/components/parameters/Api.v1.GetHomeTimelineQueryString.prevCursor' + - $ref: '#/components/parameters/Api.v1.CursorControl.nextCursor' + - $ref: '#/components/parameters/Api.v1.CursorControl.prevCursor' + - $ref: '#/components/parameters/Api.v1.CursorControl.limit' responses: '200': description: The request has succeeded. @@ -350,8 +352,8 @@ paths: - User operationId: UserApi_SearchUsers parameters: - - $ref: '#/components/parameters/Api.v1.SearchUsersQueryString.nextCursor' - - $ref: '#/components/parameters/Api.v1.SearchUsersQueryString.prevCursor' + - $ref: '#/components/parameters/Api.v1.OffsetControl.offset' + - $ref: '#/components/parameters/Api.v1.OffsetControl.limit' responses: '200': description: The request has succeeded. @@ -378,34 +380,28 @@ paths: $ref: '#/components/schemas/Api.v1.UnfollowUserBody' components: parameters: - Api.v1.GetChatRoomQueryString: - name: chatRoomId + Api.v1.CursorControl.limit: + name: limit in: query - required: true + required: false schema: type: string - Api.v1.GetChatRoomTimelineQueryString.nextCursor: + Api.v1.CursorControl.nextCursor: name: nextCursor in: query required: false schema: type: string - Api.v1.GetChatRoomTimelineQueryString.prevCursor: + Api.v1.CursorControl.prevCursor: name: prevCursor in: query required: false schema: type: string - Api.v1.GetFollowingsQueryString.nextCursor: - name: nextCursor - in: query - required: false - schema: - type: string - Api.v1.GetFollowingsQueryString.prevCursor: - name: prevCursor + Api.v1.GetChatRoomQueryString: + name: chatRoomId in: query - required: false + required: true schema: type: string Api.v1.GetFollowingsQueryString.userId: @@ -414,18 +410,6 @@ components: required: true schema: type: string - Api.v1.GetHomeTimelineQueryString.nextCursor: - name: nextCursor - in: query - required: false - schema: - type: string - Api.v1.GetHomeTimelineQueryString.prevCursor: - name: prevCursor - in: query - required: false - schema: - type: string Api.v1.GetLeafQueryString: name: leafId in: query @@ -444,38 +428,14 @@ components: required: false schema: type: string - Api.v1.SearchChatRoomsQueryString.nextCursor: - name: nextCursor - in: query - required: false - schema: - type: string - Api.v1.SearchChatRoomsQueryString.prevCursor: - name: prevCursor - in: query - required: false - schema: - type: string - Api.v1.SearchLeafsQueryString.nextCursor: - name: nextCursor + Api.v1.OffsetControl.limit: + name: limit in: query required: false schema: type: string - Api.v1.SearchLeafsQueryString.prevCursor: - name: prevCursor - in: query - required: false - schema: - type: string - Api.v1.SearchUsersQueryString.nextCursor: - name: nextCursor - in: query - required: false - schema: - type: string - Api.v1.SearchUsersQueryString.prevCursor: - name: prevCursor + Api.v1.OffsetControl.offset: + name: offset in: query required: false schema: @@ -562,6 +522,24 @@ components: properties: userId: type: string + Api.v1.GetChatRoomTimelineQueryString: + type: object + properties: + nextCursor: + type: string + prevCursor: + type: string + limit: + type: string + Api.v1.GetHomeTimelineQueryString: + type: object + properties: + nextCursor: + type: string + prevCursor: + type: string + limit: + type: string Api.v1.Leaf: type: object required: @@ -577,6 +555,27 @@ components: type: string content: type: string + Api.v1.SearchChatRoomsQueryString: + type: object + properties: + offset: + type: string + limit: + type: string + Api.v1.SearchLeafsQueryString: + type: object + properties: + offset: + type: string + limit: + type: string + Api.v1.SearchUsersQueryString: + type: object + properties: + offset: + type: string + limit: + type: string Api.v1.SigninBody: type: object required: diff --git a/spec/generated/schema.d.ts b/spec/generated/schema.d.ts index 68a0946..2b34541 100644 --- a/spec/generated/schema.d.ts +++ b/spec/generated/schema.d.ts @@ -361,12 +361,34 @@ export interface components { "Api.v1.FollowUserBody": { userId: string; }; + "Api.v1.GetChatRoomTimelineQueryString": { + nextCursor?: string; + prevCursor?: string; + limit?: string; + }; + "Api.v1.GetHomeTimelineQueryString": { + nextCursor?: string; + prevCursor?: string; + limit?: string; + }; "Api.v1.Leaf": { leafId: string; chatRoomId?: string; userId: string; content: string; }; + "Api.v1.SearchChatRoomsQueryString": { + offset?: string; + limit?: string; + }; + "Api.v1.SearchLeafsQueryString": { + offset?: string; + limit?: string; + }; + "Api.v1.SearchUsersQueryString": { + offset?: string; + limit?: string; + }; "Api.v1.SigninBody": { name: string; password?: string; @@ -392,23 +414,16 @@ export interface components { }; responses: never; parameters: { + "Api.v1.CursorControl.limit": string; + "Api.v1.CursorControl.nextCursor": string; + "Api.v1.CursorControl.prevCursor": string; "Api.v1.GetChatRoomQueryString": string; - "Api.v1.GetChatRoomTimelineQueryString.nextCursor": string; - "Api.v1.GetChatRoomTimelineQueryString.prevCursor": string; - "Api.v1.GetFollowingsQueryString.nextCursor": string; - "Api.v1.GetFollowingsQueryString.prevCursor": string; "Api.v1.GetFollowingsQueryString.userId": string; - "Api.v1.GetHomeTimelineQueryString.nextCursor": string; - "Api.v1.GetHomeTimelineQueryString.prevCursor": string; "Api.v1.GetLeafQueryString": string; "Api.v1.GetUserQueryString.userId": string; "Api.v1.GetUserQueryString.username": string; - "Api.v1.SearchChatRoomsQueryString.nextCursor": string; - "Api.v1.SearchChatRoomsQueryString.prevCursor": string; - "Api.v1.SearchLeafsQueryString.nextCursor": string; - "Api.v1.SearchLeafsQueryString.prevCursor": string; - "Api.v1.SearchUsersQueryString.nextCursor": string; - "Api.v1.SearchUsersQueryString.prevCursor": string; + "Api.v1.OffsetControl.limit": string; + "Api.v1.OffsetControl.offset": string; }; requestBodies: never; headers: never; @@ -559,8 +574,9 @@ export interface operations { ChatRoomApi_GetTimeline: { parameters: { query?: { - nextCursor?: components["parameters"]["Api.v1.GetChatRoomTimelineQueryString.nextCursor"]; - prevCursor?: components["parameters"]["Api.v1.GetChatRoomTimelineQueryString.prevCursor"]; + nextCursor?: components["parameters"]["Api.v1.CursorControl.nextCursor"]; + prevCursor?: components["parameters"]["Api.v1.CursorControl.prevCursor"]; + limit?: components["parameters"]["Api.v1.CursorControl.limit"]; }; header?: never; path?: never; @@ -582,8 +598,8 @@ export interface operations { ChatRoomApi_SearchChatRooms: { parameters: { query?: { - nextCursor?: components["parameters"]["Api.v1.SearchChatRoomsQueryString.nextCursor"]; - prevCursor?: components["parameters"]["Api.v1.SearchChatRoomsQueryString.prevCursor"]; + offset?: components["parameters"]["Api.v1.OffsetControl.offset"]; + limit?: components["parameters"]["Api.v1.OffsetControl.limit"]; }; header?: never; path?: never; @@ -725,8 +741,8 @@ export interface operations { LeafApi_SearchLeafs: { parameters: { query?: { - nextCursor?: components["parameters"]["Api.v1.SearchLeafsQueryString.nextCursor"]; - prevCursor?: components["parameters"]["Api.v1.SearchLeafsQueryString.prevCursor"]; + offset?: components["parameters"]["Api.v1.OffsetControl.offset"]; + limit?: components["parameters"]["Api.v1.OffsetControl.limit"]; }; header?: never; path?: never; @@ -792,9 +808,9 @@ export interface operations { UserApi_GetFollowings: { parameters: { query: { + offset?: components["parameters"]["Api.v1.OffsetControl.offset"]; + limit?: components["parameters"]["Api.v1.OffsetControl.limit"]; userId: components["parameters"]["Api.v1.GetFollowingsQueryString.userId"]; - nextCursor?: components["parameters"]["Api.v1.GetFollowingsQueryString.nextCursor"]; - prevCursor?: components["parameters"]["Api.v1.GetFollowingsQueryString.prevCursor"]; }; header?: never; path?: never; @@ -816,8 +832,9 @@ export interface operations { UserApi_GetHomeTimeline: { parameters: { query?: { - nextCursor?: components["parameters"]["Api.v1.GetHomeTimelineQueryString.nextCursor"]; - prevCursor?: components["parameters"]["Api.v1.GetHomeTimelineQueryString.prevCursor"]; + nextCursor?: components["parameters"]["Api.v1.CursorControl.nextCursor"]; + prevCursor?: components["parameters"]["Api.v1.CursorControl.prevCursor"]; + limit?: components["parameters"]["Api.v1.CursorControl.limit"]; }; header?: never; path?: never; @@ -862,8 +879,8 @@ export interface operations { UserApi_SearchUsers: { parameters: { query?: { - nextCursor?: components["parameters"]["Api.v1.SearchUsersQueryString.nextCursor"]; - prevCursor?: components["parameters"]["Api.v1.SearchUsersQueryString.prevCursor"]; + offset?: components["parameters"]["Api.v1.OffsetControl.offset"]; + limit?: components["parameters"]["Api.v1.OffsetControl.limit"]; }; header?: never; path?: never; diff --git a/spec/src/api/v1/models.tsp b/spec/src/api/v1/models.tsp index 5a32def..34d9adb 100644 --- a/spec/src/api/v1/models.tsp +++ b/spec/src/api/v1/models.tsp @@ -37,6 +37,19 @@ model ChatRoom { description: string; } +// utility + +model OffsetControl { + @query offset?: string; + @query limit?: string; +} + +model CursorControl { + @query nextCursor?: string; + @query prevCursor?: string; + @query limit?: string; +} + // Auth parameters model SignupBody { @@ -57,19 +70,15 @@ model GetUserQueryString { @query username?: string; } -model SearchUsersQueryString { - @query nextCursor?: string; - @query prevCursor?: string; +model SearchUsersQueryString is OffsetControl { } model DeleteUserBody { userId: string; } -model GetFollowingsQueryString { +model GetFollowingsQueryString is OffsetControl { @query userId: string; - @query nextCursor?: string; - @query prevCursor?: string; } model FollowUserBody { @@ -80,9 +89,7 @@ model UnfollowUserBody { userId: string; } -model GetHomeTimelineQueryString { - @query nextCursor?: string; - @query prevCursor?: string; +model GetHomeTimelineQueryString is CursorControl { } // Leaf parameters @@ -95,9 +102,7 @@ model GetLeafQueryString { @query leafId: string; } -model SearchLeafsQueryString { - @query nextCursor?: string; - @query prevCursor?: string; +model SearchLeafsQueryString is OffsetControl { } model DeleteLeafBody { @@ -115,9 +120,7 @@ model GetChatRoomQueryString { @query chatRoomId: string; } -model SearchChatRoomsQueryString { - @query nextCursor?: string; - @query prevCursor?: string; +model SearchChatRoomsQueryString is OffsetControl { } model DeleteChatRoomBody { @@ -129,7 +132,5 @@ model CreateChatRoomLeafBody { content: string; } -model GetChatRoomTimelineQueryString { - @query nextCursor?: string; - @query prevCursor?: string; +model GetChatRoomTimelineQueryString is CursorControl { }