diff --git a/docs/base.yaml b/docs/base.yaml new file mode 100644 index 000000000..d6323be62 --- /dev/null +++ b/docs/base.yaml @@ -0,0 +1,371 @@ +openapi: 3.1.1 +info: + version: 1.0.0 + title: Pronouns.Page API + description: |- + The Pronouns.Page API allows you to retrieve and manage pronoun data for users. + + Most of the routes listed here are considered to be public as they do not require authentication. + However, some routes may require an API key for access to private or user-specific data. + + In addition, some routes may take an optional `version` query parameter. + This parameter allows you to specify the version of the pronoun data you want to retrieve. + If not specified, version 1 will be used by default. + + > info + > We highly recommend using version 2 as that will be are LTS version. + > We may remove version 1 entirely in the future. + + ## Routes + Routing standards may be altered in the future as well. We may make a `/v1/` or `/v2/` prefix to the routes. + Please check back here for the most up-to-date information. + termsOfService: https://en.pronouns.page/terms/ + contact: + name: Support + url: https://en.pronouns.page/contact/ + email: contact@pronouns.page + license: + name: Opinionated Queer License (OQL) v1.1 + url: https://oql.avris.it/license/v1.1 +servers: + - url: https://pronouns.page/api + description: Main (production) server + - url: https://{region}.pronouns.page/api + description: Language-specific server + variables: + region: + default: en + enum: + - en + - es + - fr + - de + - it + - pt + description: The language/region of the server to use. +tags: + - name: Pronouns + description: Operations related to pronoun data + - name: Users + description: Operations related to user data +paths: + /pronouns: + get: + tags: + - Pronouns + x-beta: true + summary: Retrieve a list of pronouns + description: Get a list of all available pronouns. + responses: + '200': + description: A JSON array of pronouns + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Pronoun' + example: + - + canonicalName: he + description: Normative “he/him” + normative: true + morphemes: + pronoun_subject: he + pronoun_object: him + possessive_determiner: his + possessive_pronoun: his + reflexive: himself + pronunciations: {} + plural: false + pluralHonorific: false + aliases: + - he/him + history: "" + pronounceable: true + thirdForm: null + smallForm: null + sourcesInfo: null + nullPronoun: false + examples: + - I think he is very nice. + - I met him recently. + - Is this his dog? + - He told me that the house is his. + - He said he would rather do it himself. + - He is really beautiful. + - He answered the phone. + - He takes good care of his cat. + - He did it all by himself. + - He talks in his sleep. + - He landed the plane safely. + - He argues that… + - Did you buy him his gift? + - I asked him if I can borrow his pencil. + - I talked to him yesterday. + - Would you like to go to the movies with him? + - Can you call him when his cat awakes? + - His graduation starts soon. + - My favorite color is purple, his is yellow. + name: he/him + '500': + description: Internal server error + content: + application/json: + schema: + type: object + properties: + error: + type: string + example: Internal server error + /pronouns/{pronoun}: + get: + x-beta: true + tags: + - Pronouns + summary: Retrieve a specific pronoun set + description: Get details of a specific pronoun set by its canonical name. + parameters: + - name: pronoun + in: path + required: true + description: The canonical name of the pronoun set (e.g., "they/them"). + schema: + type: string + responses: + '200': + description: A JSON object representing the pronoun set + content: + application/json: + schema: + $ref: '#/components/schemas/Pronoun' + example: + canonicalName: they/them + description: Normative “they/them” + normative: true + morphemes: + pronoun_subject: they + pronoun_object: them + possessive_determiner: their + possessive_pronoun: theirs + reflexive: themself + pronunciations: {} + plural: true + pluralHonorific: false + aliases: + - they/them + - singular they + history: "" + pronounceable: true + thirdForm: null + smallForm: null + sourcesInfo: null + nullPronoun: false + examples: + - I think they are very nice. + - I met them recently. + - Is this their dog? + - They told me that the house is theirs. + - They said they would rather do it themself. + - They are really beautiful. + - They answered the phone. + - They take good care of their cat. + - They did it all by themself. + - They talk in their sleep. + - They landed the plane safely. + - They argue that… + - Did you buy them their gift? + - I asked them if I can borrow their pencil. + - I talked to them yesterday. + - Would you like to go to the movies with them? + - Can you call them when their cat awakes? + - Their graduation starts soon. + - My favorite color is purple, theirs is yellow. + name: they/them + '404': + description: Pronoun set not found + content: + application/json: + schema: + type: object + properties: + error: + type: string + example: Pronoun set not found + '500': + description: Internal server error + content: + application/json: + schema: + type: object + properties: + error: + type: string + example: Internal server error + /banner/{pronoun}.png: + get: + x-beta: true + tags: + - Pronouns + summary: Retrieve a pronoun badge image + description: Get a PNG image badge for a specific pronoun set by its canonical name. + parameters: + - name: pronoun + in: path + required: true + description: The canonical name of the pronoun set (e.g., "they/them"). + schema: + type: string + responses: + '200': + description: A PNG image badge representing the pronoun set + content: + image/png: + schema: + contentMediaType: image/png + '404': + description: Pronoun set not found + content: + application/json: + schema: + type: object + properties: + error: + type: string + example: Pronoun set not found + '500': + description: Internal server error + content: + application/json: + schema: + type: object + properties: + error: + type: string + example: Internal server error +components: + securitySchemes: + APIKeyHeader: + type: http + scheme: bearer + bearerFormat: JWT + description: |- + The API key used to authenticate requests. + + > info + > Note: This key is only required for requests that access private or user-specific data. + schemas: + MorphemeData: + type: object + title: Morpheme Data + required: + - pronoun_subject + - pronoun_object + - possessive_determiner + - possessive_pronoun + - reflexive + properties: + pronoun_subject: + type: string + description: Subject pronoun (e.g., "they"). + example: they + pronoun_object: + type: string + description: Object pronoun (e.g., "them"). + example: them + possessive_determiner: + type: string + description: Possessive determiner (e.g., "their"). + example: their + possessive_pronoun: + type: string + description: Possessive pronoun (e.g., "theirs"). + example: theirs + reflexive: + type: string + description: Reflexive pronoun (e.g., "themself"). + example: themself + Pronoun: + type: object + title: Pronoun Data + required: + - canonicalName + - description + - normative + - morphemes + - pronunciations + - plural + - pluralHonorific + - pronounceable + - nullPronoun + - name + properties: + canonicalName: + type: string + description: The canonical name of the pronoun set (e.g., "they/them"). + example: they/them + description: + type: string + description: A brief description of the pronoun set. + normative: + type: boolean + description: Indicates if the pronoun set is considered normative. + example: true + morphemes: + type: object + description: The morpheme data for the pronoun set. + $ref: '#/components/schemas/MorphemeData' + pronunciations: + type: object + description: Pronunciation guides for the pronoun set. + plural: + type: boolean + description: Indicates if the pronoun set is plural. + example: true + pluralHonorific: + type: boolean + description: Indicates if the pronoun set is a plural honorific. + example: false + aliases: + type: array + description: Alternative names or aliases for the pronoun set. + items: + type: string + history: + type: string + description: Historical context or notes about the pronoun set. + pronounceable: + type: boolean + description: Indicates if the pronoun set is easily pronounceable. + example: true + thirdForm: + type: string + description: A third form of the pronoun set, if applicable. + smallForm: + type: string + description: A smaller or abbreviated form of the pronoun set, if applicable. + sourcesInfo: + type: string + description: Information about the sources of the pronoun set. + nullPronoun: + type: boolean + description: Indicates if the pronoun set is a null pronoun. + example: false + examples: + type: array + description: Example sentences or phrases using the pronoun set. + items: + type: string + name: + type: string + description: A human-readable name for the pronoun set. + example: They/Them + Item: + type: object + properties: + id: + type: integer + example: 1 + name: + type: string + example: Item 1 diff --git a/docs/docs.plist b/docs/docs.plist new file mode 100644 index 000000000..d2f0468cb Binary files /dev/null and b/docs/docs.plist differ diff --git a/docs/en.yaml b/docs/en.yaml new file mode 100644 index 000000000..9bb42cd90 --- /dev/null +++ b/docs/en.yaml @@ -0,0 +1,33 @@ +openapi: 3.1.1 +info: + version: 1.0.0 + title: Pronouns.Page API + description: |- + The Pronouns.Page API allows you to retrieve and manage pronoun data for users. + termsOfService: https://en.pronouns.page/terms/ + contact: + name: Support + url: https://en.pronouns.page/contact/ + email: contact@pronouns.page + license: + name: Opinionated Queer License (OQL) v1.1 + url: https://oql.avris.it/license/v1.1 +servers: + - url: https://pronouns.page/api + description: Main (production) server + - url: https://{region}.pronouns.page/api + description: Language-specific server + variables: + region: + default: en + enum: + - en + - es + - fr + - de + - it + - pt + description: The language/region of the server to use. +paths: + /pronouns: + $ref: './base.yaml#/paths/pronouns';