From ee07e30d6dd11f0e3325139ee564d8232a19b3a8 Mon Sep 17 00:00:00 2001 From: Kris Date: Sat, 30 Nov 2024 18:28:15 +0100 Subject: [PATCH] :memo: update API docs (#3015) --- storage/api-docs/api-docs.json | 66 +++++++++++++++++++++++++--------- 1 file changed, 50 insertions(+), 16 deletions(-) diff --git a/storage/api-docs/api-docs.json b/storage/api-docs/api-docs.json index 7725f50d8..f5a1423e6 100644 --- a/storage/api-docs/api-docs.json +++ b/storage/api-docs/api-docs.json @@ -105,7 +105,7 @@ "Auth" ], "summary": "Refresh Bearer Token", - "description": "This request issues a new Bearer-Token with a new expiration date while also revoking the old\r\n * token.", + "description": "This request issues a new Bearer-Token with a new expiration date while also revoking the old\n * token.", "operationId": "refreshToken", "responses": { "200": { @@ -828,7 +828,7 @@ "Likes" ], "summary": "[Auth optional] Get likes for status", - "description": "Returns array of users that liked the status. Can return an empty dataset when the status\r\n * author or the requesting user has deactivated likes", + "description": "Returns array of users that liked the status. Can return an empty dataset when the status\n * author or the requesting user has deactivated likes", "operationId": "getLikesForStatus", "parameters": [ { @@ -1572,7 +1572,7 @@ "Checkin" ], "summary": "Search for stations", - "description": "UNSTABLE: This request returns an array of max. 20 station objects matching the query. **CAUTION:** All\r\n * slashes (as well as encoded to %2F) in {query} need to be replaced, preferrably by a space (%20)", + "description": "UNSTABLE: This request returns an array of max. 20 station objects matching the query. **CAUTION:** All\n * slashes (as well as encoded to %2F) in {query} need to be replaced, preferrably by a space (%20)", "operationId": "indexStation", "parameters": [ { @@ -1854,7 +1854,7 @@ "example": 11 }, "duration": { - "description": "Duration in\r\n * minutes", + "description": "Duration in\n * minutes", "type": "integer", "example": 425 } @@ -1985,7 +1985,7 @@ { "name": "withPolylines", "in": "query", - "description": "If this parameter is set, the polylines will be returned as well. Otherwise attribute is\r\n * null.", + "description": "If this parameter is set, the polylines will be returned as well. Otherwise attribute is\n * null.", "schema": { "type": "boolean" } @@ -2251,7 +2251,7 @@ "Dashboard" ], "summary": "Get paginated future statuses of current user", - "description": "Returns paginated statuses of the authenticated user, that are more than 20 minutes in the\r\n * future", + "description": "Returns paginated statuses of the authenticated user, that are more than 20 minutes in the\n * future", "operationId": "getFutureDashboard", "parameters": [ { @@ -2862,7 +2862,7 @@ "Status" ], "summary": "Create a StatusTag", - "description": "Creates a single StatusTag Object, if user is authorized to.

The key of a tag is free\r\n * text. You can choose it as you need it. However, please use a namespace for tags\r\n * (namespace:xxx) that only affect your own application.

For tags related to standard actions\r\n * we recommend the following tags in the trwl namespace:
\r\n * ", + "description": "Creates a single StatusTag Object, if user is authorized to.

The key of a tag is free\n * text. You can choose it as you need it. However, please use a namespace for tags\n * (namespace:xxx) that only affect your own application.

For tags related to standard actions\n * we recommend the following tags in the trwl namespace:
\n * ", "operationId": "createSingleStatusTag", "parameters": [ { @@ -3626,7 +3626,7 @@ "Checkin" ], "summary": "Autocomplete for stations", - "description": "This request returns an array of max. 10 station objects matching the query. **CAUTION:** All\r\n * slashes (as well as encoded to %2F) in {query} need to be replaced, preferrably by a space (%20)", + "description": "This request returns an array of max. 10 station objects matching the query. **CAUTION:** All\n * slashes (as well as encoded to %2F) in {query} need to be replaced, preferrably by a space (%20)", "operationId": "trainStationAutocomplete", "parameters": [ { @@ -3680,7 +3680,7 @@ "Checkin" ], "summary": "History for stations", - "description": "This request returns an array of max. 10 most recent station objects that the user has arrived\r\n * at.", + "description": "This request returns an array of max. 10 most recent station objects that the user has arrived\n * at.", "operationId": "trainStationHistory", "responses": { "200": { @@ -3932,7 +3932,7 @@ "properties": { "confirmation": { "title": "confirmation", - "description": "Username of the to be deleted account (needs to match the currently logged in\r\n * user)", + "description": "Username of the to be deleted account (needs to match the currently logged in\n * user)", "example": "Gertrud123" } }, @@ -4109,7 +4109,7 @@ "User/Hide and Block" ], "summary": "Block a user", - "description": "Block a specific user. That user will not be able to see your statuses or profile information,\r\n * and cannot send you follow requests. Public statuses are still visible through the incognito mode.", + "description": "Block a specific user. That user will not be able to see your statuses or profile information,\n * and cannot send you follow requests. Public statuses are still visible through the incognito mode.", "operationId": "createBlock", "requestBody": { "required": true, @@ -4177,7 +4177,7 @@ "User/Hide and Block" ], "summary": "Unmute a user", - "description": "Unblock a specific user. They are now able to see your statuses and profile information again,\r\n * and send you follow requests.", + "description": "Unblock a specific user. They are now able to see your statuses and profile information again,\n * and send you follow requests.", "operationId": "destroyBlock", "requestBody": { "required": true, @@ -4247,7 +4247,7 @@ "User/Hide and Block" ], "summary": "Mute a user", - "description": "Mute a specific user. That way they will not be shown on your dashboard and in the active\r\n * journeys tab", + "description": "Mute a specific user. That way they will not be shown on your dashboard and in the active\n * journeys tab", "operationId": "createMute", "parameters": [ { @@ -4305,7 +4305,7 @@ "User/Hide and Block" ], "summary": "Unmute a user", - "description": "Unmute a specific user. That way they will be shown on your dashboard and in the active\r\n * journeys tab again", + "description": "Unmute a specific user. That way they will be shown on your dashboard and in the active\n * journeys tab again", "operationId": "destroyMute", "parameters": [ { @@ -4565,6 +4565,40 @@ } ] } + }, + "/year-in-review": { + "get": { + "tags": [ + "Statistics" + ], + "summary": "Returns the year in review for the given year and authenticated user", + "description": "Please note: This endpoint is only available when the year in review feature is enabled in the backend configuration. There is no full documentation - this endpoint may change every year.", + "operationId": "getYearInReview", + "responses": { + "200": { + "description": "JSON object with the year in review data. The structure of the object may change every year. There is no full documentation at this point." + }, + "400": { + "description": "Bad request" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Year in review is not active" + } + }, + "security": [ + { + "passport": [ + "create-statuses" + ] + }, + { + "token": [] + } + ] + } } }, "components": { @@ -4785,7 +4819,7 @@ }, "MastodonVisibility": { "title": "visibility", - "description": "What type of visibility (0=public, 1=unlisted, 2=followers, 3=private) did the user specify for\r\n * future posts to Mastodon? Some instances such as chaos.social discourage bot posts on public timelines.", + "description": "What type of visibility (0=public, 1=unlisted, 2=followers, 3=private) did the user specify for\n * future posts to Mastodon? Some instances such as chaos.social discourage bot posts on public timelines.", "type": "integer", "enum": [ 0, @@ -4811,7 +4845,7 @@ }, "StatusVisibility": { "title": "visibility", - "description": "What type of visibility (0=public, 1=unlisted, 2=followers, 3=private, 4=authenticated) did the\r\n * user specify?", + "description": "What type of visibility (0=public, 1=unlisted, 2=followers, 3=private, 4=authenticated) did the\n * user specify?", "type": "integer", "enum": [ 0,