From 38e65b39718362bf15a25e8fe78c93c889f23caa Mon Sep 17 00:00:00 2001 From: Ske Date: Thu, 7 May 2020 01:36:00 +0200 Subject: [PATCH] Properly publish OpenAPI spec --- PluralKit.API/openapi.yaml | 28 +++++++++++++++++++++++----- docs/4-api-documentation.md | 5 +++++ 2 files changed, 28 insertions(+), 5 deletions(-) diff --git a/PluralKit.API/openapi.yaml b/PluralKit.API/openapi.yaml index 5ab382fd..224832fb 100644 --- a/PluralKit.API/openapi.yaml +++ b/PluralKit.API/openapi.yaml @@ -8,6 +8,8 @@ info: description: | This is the API for [PluralKit](https://pluralkit.me/)! :) + The API itself is stable, but this document (the OpenAPI description) is still subject to change, and may be updated, corrected or restructured in the future (as long as it's still coherent with the real API). + # Authentication Authentication is handled using a "system token". At the moment, the only way to obtain a system token is to use the `pk;token` command through the Discord bot. @@ -20,6 +22,14 @@ info: Errors are just returned as HTTP response codes. Most error responses include a human-readable error message as the body, but this should not be relied on. Just read the response codes :) + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + +externalDocs: + url: https://pluralkit.me/api + description: For more information, see the official PluralKit API documentation on the website. + servers: - url: https://api.pluralkit.me/v1 description: Primary API server (v1) @@ -360,6 +370,7 @@ components: schemas: ID: + title: ID (system or member) type: string readOnly: true minLength: 5 @@ -608,6 +619,7 @@ components: Whether or not to include the used proxy tags in proxied messages. PrivacySetting: + title: Privacy Setting type: string nullable: true description: A privacy setting for systems or members, either public or private. May occasionally be `null` in cases where you are not authorized to view the privacy setting's state. @@ -615,13 +627,15 @@ components: example: public ProxyTag: + title: Proxy Tag description: | - Represents a set of proxy tags to match messages on. + Represents a proxy tag to match messages on. A "proxy tag" consists of a prefix and a suffix, and a given proxy tag set matches a string - if that string begins with the prefix and ends with the suffix. They're often represented to the user with the word `text` between them, eg. `[text]`, `{{text`, etc. + if that string begins with the prefix and ends with the suffix. + It's often represented to the user with the word `text` between them, eg. `[text]`, `{{text`, and so on. - For example, the proxy tag pair "[" and "]" will match any string [in square brackets]. + For example, the proxy tag pair "[" and "]" will match any string \[in square brackets\]. Either the prefix or the suffix may be missing (or both may be present), but it is invalid for both values to be null. @@ -646,6 +660,7 @@ components: maxLength: 100 Switch: + title: Logged Switch properties: timestamp: type: string @@ -660,7 +675,7 @@ components: $ref: "#/components/schemas/ID" FullSwitch: - description: A variant of the Switch schema where the full Member object is contained instead of just IDs. + title: Logged Switch (with full Member object) properties: timestamp: type: string @@ -674,6 +689,7 @@ components: $ref: "#/components/schemas/Member" Snowflake: + title: Snowflake (Discord ID) description: | A unique identifier used by Discord for its objects (accounts, guilds, channels, messages). @@ -686,6 +702,7 @@ components: example: 466378653216014359 # PK's account ID :3 Message: + title: Message Info description: | An object containing information about a proxied message, including message, user and channel IDs, as well as the system and member it's related to. @@ -725,4 +742,5 @@ components: TokenAuth: type: apiKey in: header - name: Authorization \ No newline at end of file + name: Authorization + description: A system token obtained from the `pk;proxy` command in the Discord bot. \ No newline at end of file diff --git a/docs/4-api-documentation.md b/docs/4-api-documentation.md index 673deeff..b2979eb7 100644 --- a/docs/4-api-documentation.md +++ b/docs/4-api-documentation.md @@ -6,6 +6,9 @@ description: PluralKit's API documentation. nav_order: 4 --- +**2020-05-07**: The PluralKit API is now documented on Swagger: https://app.swaggerhub.com/apis-docs/xSke/PluralKit/1.0 +Accompanying it is an [OpenAPI v3.0 definition](https://github.com/xSke/PluralKit/blob/master/PluralKit.API/openapi.yaml). It's mostly complete, but is still subject to change - so don't go generating API clients and mock servers with it quite yet. It may still be useful, though :) + # API documentation PluralKit has a basic HTTP REST API for querying and modifying your system. The root endpoint of the API is `https://api.pluralkit.me/v1/`. @@ -462,6 +465,8 @@ The returned system and member's privacy settings will be respected, and as such ``` ## Version history +* 2020-05-07 + * The API (v1) is now formally(ish) defined with OpenAPI v3.0. [The definition file can be found here.](https://github.com/xSke/PluralKit/blob/master/PluralKit.API/openapi.yaml) * 2020-02-10 * Birthdates with no year can now be stored using `0004` as a year, for better leap year support. Both options remain valid and either may be returned by the API. * Added privacy set/get support, meaning you will now see privacy values in authed requests and can set them.