Add initial schema files
This commit is contained in:
Ciarán Ainsworth
parent
65ad329758
commit
2981d31b86
|
|
@ -0,0 +1,103 @@
|
||||||
|
openapi: 3.1.0
|
||||||
|
info:
|
||||||
|
description: "Interactive documentation for [Funkwhale](https://funkwhale.audio) API."
|
||||||
|
version: "2.0.0"
|
||||||
|
title: "Funkwhale API"
|
||||||
|
servers:
|
||||||
|
- url: "https://demo.funkwhale.audio"
|
||||||
|
description: "Demo server"
|
||||||
|
- url: "https://open.audio"
|
||||||
|
description: "Real server with real content"
|
||||||
|
- url: "https://{domain}"
|
||||||
|
description: "Custom server"
|
||||||
|
variables:
|
||||||
|
domain:
|
||||||
|
default: yourdomain
|
||||||
|
description: "Your Funkwhale Domain"
|
||||||
|
protocol:
|
||||||
|
enum:
|
||||||
|
- "http"
|
||||||
|
- "https"
|
||||||
|
default: "https"
|
||||||
|
tags:
|
||||||
|
- name: Users
|
||||||
|
paths:
|
||||||
|
/api/v2/users:
|
||||||
|
$ref: "users/schema.yml#/paths/~1users"
|
||||||
|
components:
|
||||||
|
parameters:
|
||||||
|
PageParam:
|
||||||
|
name: page
|
||||||
|
in: query
|
||||||
|
required: false
|
||||||
|
description: The number of the result page you want to return
|
||||||
|
schema:
|
||||||
|
type: number
|
||||||
|
format: integer
|
||||||
|
PageSizeParam:
|
||||||
|
name: page_size
|
||||||
|
in: query
|
||||||
|
required: false
|
||||||
|
description: The number of results to return on each page. Defaults to 50.
|
||||||
|
schema:
|
||||||
|
type: number
|
||||||
|
default: 50
|
||||||
|
Query:
|
||||||
|
name: q
|
||||||
|
in: query
|
||||||
|
required: false
|
||||||
|
description: A free text field to filter results
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
schemas:
|
||||||
|
ImageUrls:
|
||||||
|
type: object
|
||||||
|
description: "Metadata and file links for the object's associated art"
|
||||||
|
required:
|
||||||
|
- guid
|
||||||
|
- mimetype
|
||||||
|
- size
|
||||||
|
- creationDate
|
||||||
|
- urls
|
||||||
|
properties:
|
||||||
|
guid:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
description: "The unique ID of the cover"
|
||||||
|
mimetype:
|
||||||
|
type: string
|
||||||
|
description: "The data type (filetype) of the cover file"
|
||||||
|
size:
|
||||||
|
type: integer
|
||||||
|
description: "The size of the file"
|
||||||
|
creationDate:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
description: "The date and time on which the cover object was created"
|
||||||
|
urls:
|
||||||
|
type: object
|
||||||
|
description: "All URLs associated with the cover"
|
||||||
|
required:
|
||||||
|
- original
|
||||||
|
properties:
|
||||||
|
source:
|
||||||
|
type: string
|
||||||
|
format: url
|
||||||
|
description: "The source of the cover"
|
||||||
|
original:
|
||||||
|
type: string
|
||||||
|
format: url
|
||||||
|
description: "The upload in its original size and format"
|
||||||
|
Pagination:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- total
|
||||||
|
properties:
|
||||||
|
total:
|
||||||
|
type: integer
|
||||||
|
next:
|
||||||
|
type: string
|
||||||
|
format: url
|
||||||
|
previous:
|
||||||
|
type: string
|
||||||
|
format: url
|
||||||
|
|
@ -0,0 +1,131 @@
|
||||||
|
paths:
|
||||||
|
/users:
|
||||||
|
get:
|
||||||
|
tags:
|
||||||
|
- Users
|
||||||
|
summary: "Fetch a list of users"
|
||||||
|
description: "Fetch a list of users from the server"
|
||||||
|
operationId: getUsers
|
||||||
|
parameters:
|
||||||
|
- $ref: "../schema.yml#/components/parameters/Query"
|
||||||
|
- $ref: "../schema.yml#/components/parameters/PageParam"
|
||||||
|
- $ref: "../schema.yml#/components/parameters/PageSizeParam"
|
||||||
|
responses:
|
||||||
|
"200":
|
||||||
|
description: Successful operation
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
allOf:
|
||||||
|
- $ref: "../schema.yml#/components/schemas/Pagination"
|
||||||
|
- type: object
|
||||||
|
required:
|
||||||
|
- results
|
||||||
|
properties:
|
||||||
|
results:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: "#/components/schemas/SimpleUser"
|
||||||
|
example:
|
||||||
|
total: 1
|
||||||
|
results:
|
||||||
|
- guid: "eaf72973-b62b-45ed-8549-f427919e6555"
|
||||||
|
username: "betterraves"
|
||||||
|
preferredUsername: "betterraves"
|
||||||
|
domain: "https://open.audio"
|
||||||
|
name: "Agate"
|
||||||
|
components:
|
||||||
|
schemas:
|
||||||
|
SimpleUser:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- guid
|
||||||
|
- username
|
||||||
|
- preferredUsername
|
||||||
|
- domain
|
||||||
|
properties:
|
||||||
|
guid:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
description: "The unique ID of the user"
|
||||||
|
username:
|
||||||
|
type: string
|
||||||
|
description: "The user's account username"
|
||||||
|
preferredUsername:
|
||||||
|
type: string
|
||||||
|
description: "The username displayed on the user's profile"
|
||||||
|
domain:
|
||||||
|
type: string
|
||||||
|
format: url
|
||||||
|
description: "The domain the user belongs to"
|
||||||
|
name:
|
||||||
|
type: string
|
||||||
|
description: "The user's real name"
|
||||||
|
User:
|
||||||
|
allOf:
|
||||||
|
- $ref: "#/components/schemas/SimpleUser"
|
||||||
|
- type: object
|
||||||
|
properties:
|
||||||
|
createdDate:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
description: "The date and time the user profile was created"
|
||||||
|
summary:
|
||||||
|
type: string
|
||||||
|
format: html
|
||||||
|
description: "A brief summary of the user"
|
||||||
|
avatar:
|
||||||
|
$ref: "../schema.yml#/components/schemas/ImageUrls"
|
||||||
|
SimpleActor:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- fid
|
||||||
|
- preferredUsername
|
||||||
|
- fullUsername
|
||||||
|
- local
|
||||||
|
- domain
|
||||||
|
properties:
|
||||||
|
fid:
|
||||||
|
type: string
|
||||||
|
format: url
|
||||||
|
description: "The federation ID of the actor"
|
||||||
|
fullUsername:
|
||||||
|
type: string
|
||||||
|
description: "The username and domain of the actor"
|
||||||
|
preferredUsername:
|
||||||
|
type: string
|
||||||
|
description: "The user-selected preferred username"
|
||||||
|
name:
|
||||||
|
type: string
|
||||||
|
description: "The name of the actor"
|
||||||
|
domain:
|
||||||
|
type: string
|
||||||
|
description: "The domain the actor is associated with"
|
||||||
|
local:
|
||||||
|
type: boolean
|
||||||
|
description: "Whether the actor belongs to the server serving the request"
|
||||||
|
Actor:
|
||||||
|
allOf:
|
||||||
|
- $ref: "#/components/schemas/SimpleActor"
|
||||||
|
- type: object
|
||||||
|
properties:
|
||||||
|
lastFetchDate:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
description: "The date and time on which the server last fetched information about the actor"
|
||||||
|
manuallyApprovesFollowers:
|
||||||
|
type: boolean
|
||||||
|
description: "Whether the user manually approves followers"
|
||||||
|
type:
|
||||||
|
type: string
|
||||||
|
description: "The type of ActivityPub actor the object represents"
|
||||||
|
enum:
|
||||||
|
- person
|
||||||
|
- tombstone
|
||||||
|
- application
|
||||||
|
- group
|
||||||
|
- organization
|
||||||
|
- service
|
||||||
|
url:
|
||||||
|
type: string
|
||||||
|
format: url
|
||||||
Loading…
Reference in New Issue