mirror of
https://gitlab.com/PronounsPage/PronounsPage.git
synced 2025-09-22 12:03:25 -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