mirror of
https://gitlab.com/PronounsPage/PronounsPage.git
synced 2025-09-23 04:34:15 -04:00
Merge branch 'benpai-openapi' into 'main'
Draft: docs(api): add in openAPI v3.1.1 docs for API routes See merge request PronounsPage/PronounsPage!651
This commit is contained in:
Benjamin
commit
35d654d5e1
371
docs/base.yaml
Normal file
371
docs/base.yaml
Normal file
@ -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
|
||||||
BIN
docs/docs.plist
Normal file
BIN
docs/docs.plist
Normal file
Binary file not shown.
33
docs/en.yaml
Normal file
33
docs/en.yaml
Normal file
@ -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';
|
||||||
Loading…
x
Reference in New Issue
Block a user