From 7b7b0ca15b83b0a2f3d93075e1a7955ec7363a35 Mon Sep 17 00:00:00 2001 From: Sam Date: Mon, 12 Dec 2022 14:18:36 +0100 Subject: [PATCH] docs: start writing OpenAPI definition --- openapi.yml | 234 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 234 insertions(+) create mode 100644 openapi.yml diff --git a/openapi.yml b/openapi.yml new file mode 100644 index 0000000..6c72508 --- /dev/null +++ b/openapi.yml @@ -0,0 +1,234 @@ +openapi: 3.1.0 +info: + title: pronouns.cc API + version: 1.0.0 +servers: + - url: https://pronouns.cc/api/v1 +paths: + /users/{userRef}: + parameters: + - name: userRef + in: path + required: true + schema: + anyOf: + - $ref: "#/components/schemas/xid" + - $ref: "#/components/schemas/name" + get: + summary: /users/{userRef} + description: Get a user's information. + tags: [Users] + operationId: GetUser + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/User" + "404": + description: No user with that name or ID found. + content: + application/json: + schema: + $ref: "#/components/schemas/APIError" +components: + schemas: + XID: + title: ID + type: string + readOnly: true + minLength: 20 + maxLength: 20 + pattern: "^[0-9a-v]{20}$" + example: "ce6v1aje6i88cb6k5heg" + description: A unique, unchanging identifier for a user or a member. + Name: + title: Name + type: string + readOnly: false + minLength: 2 + maxLength: 40 + pattern: "^[\\w-.]{2,40}$" + example: "testingUser" + description: A user-defined identifier for a user or a member. + + WordStatus: + type: integer + oneOf: + - title: Favourite + const: 1 + description: Name/pronouns is user's/member's favourite + - title: Okay + const: 2 + description: Name/pronouns is okay to use + - title: Jokingly + const: 3 + description: Name/pronouns should only be used jokingly + - title: Friends only + const: 4 + description: Name/pronouns can only be used by friends + - title: Avoid + const: 5 + description: Name/pronouns should be avoided + example: 2 + description: Status for name/pronouns. + + Names: + type: array + items: + type: object + properties: + name: + type: string + required: true + minLength: 1 + maxLength: 50 + summary: A single name entry. + example: "Testington" + status: + $ref: "#/components/schemas/WordStatus" + description: Array of user's/member's name preferences. + + Pronouns: + type: array + items: + type: object + properties: + pronouns: + type: string + required: true + minLength: 1 + maxLength: 50 + summary: A single pronouns entry. + example: "it/it/its/its/itself" + display_text: + type: string + required: false + nullable: true + minLength: 1 + maxLenght: 50 + summary: A pronoun's display text. If not present, the first two forms (separated by /) in `pronouns` is used. + example: "it/its" + status: + $ref: "#/components/schemas/WordStatus" + description: Array of user's/member's pronoun preferences. + + Field: + type: object + properties: + name: + type: string + nullable: false + required: true + minLength: 1 + maxLength: 100 + example: "Name" + description: The field's name. + favourite: + type: array + items: + type: string + description: The field's favourite entries. + okay: + type: array + items: + type: string + description: The field's okay entries. + jokingly: + type: array + items: + type: string + description: The field's joking entries. + friends_only: + type: array + items: + type: string + description: The field's friends only entries. + avoid: + type: array + items: + type: string + description: The field's avoid entries. + + User: + type: object + properties: + id: + $ref: "#/components/schemas/XID" + name: + $ref: "#/components/schemas/Name" + display_name: + type: string + nullable: true + readOnly: false + minLength: 1 + maxLength: 100 + example: "Testington, Head Tester" + description: An optional nickname. + bio: + type: string + nullable: true + readOnly: false + minLength: 1 + maxLength: 1000 + example: "Hi! I'm a user!" + description: An optional bio/description. + avatar_urls: + type: array + nullable: true + items: + type: string + readOnly: true + example: ["https://pronouns.cc/avatars/members/ce6v1aje6i88cb6k5heg.webp", "https://pronouns.cc/avatars/members/ce6v1aje6i88cb6k5heg.jpg"] + description: | + An optional array of avatar URLs. + The first entry is the canonical avatar URL (the one that should be used if possible), + if the array has more entries, those are alternative formats. + links: + type: array + nullable: true + items: + type: string + minLength: 1 + maxLength: 256 + readOnly: false + example: ["https://pronouns.cc", "https://codeberg.org/u1f320"] + description: An optional array of links associated with the user. + names: + $ref: "#/components/schemas/Names" + pronouns: + $ref: "#/components/schemas/Pronouns" + fields: + type: array + nullable: true + items: + $ref: "#/components/schemas/Field" + + APIError: + type: object + properties: + code: + type: integer + optional: false + nullable: false + readOnly: true + description: A machine-readable error code. + message: + type: string + optional: false + nullable: false + readOnly: true + description: A human-readable error string. + details: + type: string + optional: true + nullable: false + readOnly: true + description: Human-readable details, if applicable. + ratelimit_reset: + type: integer + optional: true + nullable: false + readOnly: true + description: Unix timestamp after which you can make requests again, if this is a rate limit error. \ No newline at end of file