docs: start writing OpenAPI definition

This commit is contained in:
Sam 2022-12-12 14:18:36 +01:00
parent 6b5ccae514
commit 7b7b0ca15b
No known key found for this signature in database
GPG Key ID: B4EF20DDE721CAA1
1 changed files with 234 additions and 0 deletions

234
openapi.yml Normal file
View File

@ -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.