mirror of
https://gitlab.com/PronounsPage/PronounsPage.git
synced 2025-09-24 05:05:20 -04:00
docs(api): add in openAPI v3.1.1 docs for API routes
Add in directly declared OpenAPI version 3.3.1 documentation for all public API routes to allow for more standardized documentation
This commit is contained in:
Benjamin
parent
9fb603e289
commit
3f55ff1c26
306
docs/openapi.yaml
Normal file
306
docs/openapi.yaml
Normal file
@ -0,0 +1,306 @@
|
||||
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: http://en.pronouns.page/terms/
|
||||
contact:
|
||||
name: Support
|
||||
url: http://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:
|
||||
get:
|
||||
x-state: In Development
|
||||
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-state: In Development
|
||||
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
|
||||
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
|
||||
Loading…
x
Reference in New Issue
Block a user