MirrorMirror
/
funkwhale
mirror of https://dev.funkwhale.audio/funkwhale/funkwhale.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

#1171 fix validity issues in openapi/swagger spec files

This commit is contained in:
poeppe 2022-06-10 09:56:36 +00:00 committed by Georg Krause
parent b8de2d0b14
commit 68534e6baa
4 changed files with 261 additions and 180 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
changes/changelog.d/1171.bugfix Normal file
View File

@ -0,0 +1 @@
Fix validity issues in openapi/swagger spec files (#1171)

44
docs/api/definitions.yml
View File

@ -118,9 +118,14 @@ Actor:
BaseArtist:
type: "object"
required:
- id
- fid
- name
- creation_date
- is_local
properties:
mbid:
required: false
$ref: "./properties.yml#/mbid"
id:
type: "integer"
@ -157,9 +162,16 @@ Artist:
BaseAlbum:
type: "object"
required:
- id
- fid
- artist
- title
- creation_date
- is_playable
- is_local
properties:
mbid:
required: false
$ref: "./properties.yml#/mbid"
id:
type: "integer"
@ -181,7 +193,6 @@ BaseAlbum:
format: "date-time"
release_date:
type: "string"
required: false
format: "date"
example: "2001-01-01"
is_playable:
@ -258,7 +269,7 @@ ChannelCreate:
type: string
format: uuid
metadata:
$ref: "#ChannelMetadata"
$ref: "#/ChannelMetadata"
ChannelUpdate:
type: "object"
properties:
@ -399,9 +410,18 @@ License:
BaseTrack:
type: "object"
required:
- id
- fid
- artist
- album
- title
- listen_url
- copyright
- license
- is_local
properties:
mbid:
required: false
$ref: "./properties.yml#/mbid"
id:
type: "integer"
@ -423,13 +443,11 @@ BaseTrack:
type: "string"
example: "Chop Suey!"
position:
required: false
description: "Position of the track in the album"
type: "number"
minimum: 1
example: 1
disc_number:
required: false
type: "number"
minimum: 1
example: 1
@ -547,12 +565,14 @@ Upload:
OwnedLibraryCreate:
type: "object"
required:
- name
- privacy_level
properties:
name:
type: "string"
example: "My new library"
description:
required: false
type: "string"
example: "Lots of interesting content"
privacy_level:
@ -668,28 +688,26 @@ PlaylistTrack:
ImportMetadata:
type: "object"
required:
- title
- position
description: "Import metadata to override values from ID3/embedded audio tags"
properties:
title:
type: "string"
example: "My Track"
required: true
mbid:
$ref: "./properties.yml#/mbid"
required: false
copyright:
type: "string"
example: "Alice, 2018"
description: "Copyright information"
required: false
license:
type: "string"
example: "cc-by-sa-4.0"
required: false
description: A license code, as returned by /api/v1/licenses
tags:
$ref: "./properties.yml#/tags"
required: false
position:
description: "Position of the track in the album or channel"
type: "number"

93
docs/api/parameters.yml
View File

@ -1,21 +1,73 @@
ChannelOrdering:
- $ref: "#/Ordering"
- default: "-creation_date"
schema:
$ref: "#/Ordering"
required: false
schema:
type: "string"
example: "-creation_date"
default: "creation_date"
example: "creation_date"
enum:
- creation_date
- artist__modification_date
PlaylistOrdering:
$ref: "#/Ordering"
required: false
schema:
type: "string"
default: "creation_date"
example: "creation_date"
enum:
- creation_date
- modification_date
- id
- name
ArtistOrdering:
$ref: "#/Ordering"
required: false
schema:
type: "string"
default: "creation_date"
example: "creation_date"
enum:
- creation_date
- id
- name
- random
AlbumOrdering:
$ref: "#/Ordering"
required: false
schema:
type: "string"
default: "creation_date"
example: "creation_date"
enum:
- creation_date
- release_date
- title
- random
TrackOrdering:
$ref: "#/Ordering"
required: false
schema:
type: "string"
default: "creation_date"
example: "creation_date"
enum:
- creation_date
- release_date
- title
- random
External:
name: "external"
in: "query"
default: null
required: false
description: "Filter/exclude channels created from a third-party, non-Funkwhale RSS feed"
schema:
required: false
default: null
type: "boolean"
@ -62,26 +114,26 @@ PageSize:
Playable:
name: "playable"
in: "query"
default: null
required: false
description: "Filter/exclude resources with playable tracks"
schema:
required: false
default: null
type: "boolean"
HasAlbums:
name: "has_albums"
in: "query"
default: null
required: false
description: "Filter/exclude artists with no associated albums"
schema:
required: false
default: null
type: "boolean"
Refresh:
name: "refresh"
in: "query"
default: false
required: false
description: "Trigger an ActivityPub fetch to refresh local data"
schema:
required: false
default: false
type: "boolean"
@ -97,7 +149,7 @@ Related:
Scope:
name: "scope"
in: "query"
default: "all"
required: false
description: |
Limit the results to a given user or pod:
- Use `all` (or do not specify the property to disable scope filtering)
@ -109,7 +161,7 @@ Scope:
You can specify multiple coma separated scopes, e.g `scope=me,subscribed` to retrieve content matching either scopes.
schema:
required: false
default: "all"
type: "string"
enum:
- "me"
@ -124,8 +176,8 @@ ContentCategory:
description: |
Limits the results to those whose artist content type matches the query.
schema:
required: false
schema:
type: "string"
enum:
- "podcast"
@ -134,10 +186,10 @@ ContentCategory:
Search:
name: "q"
in: "query"
default: "all"
required: false
description: "Limit the results to the corresponding search query"
schema:
required: false
default: "all"
type: "string"
example: "Bonobo"
@ -145,18 +197,19 @@ Subscribed:
name: "subscribed"
in: "query"
description: "Limit or exclude results with a matching subsription from the current user"
schema:
required: false
schema:
type: boolean
Tags:
name: "tag"
in: "query"
description: "Limit the results to the corresponding tags. May be used multiple times, to retrieve objects matching al provided tags"
schema:
required: false
schema:
type: array
collectionFormat: csv
items:
type: string
example:
- rock
- metal

241
docs/swagger.yml
View File

@ -134,6 +134,15 @@ servers:
default: 'https'
components:
responses:
200:
description: Success
201:
description: Successfully created
204:
description: Successfully deleted
400:
description: Bad request
securitySchemes:
oauth2:
type: oauth2
@ -210,6 +219,7 @@ paths:
security: []
responses:
201:
description: ""
content:
application/json:
schema:
@ -226,14 +236,14 @@ paths:
name:
type: "string"
example: "My Awesome Funkwhale Client"
summary: "A human readable name for your app"
description: "A human readable name for your app"
redirect_uris:
type: "string"
example: "https://myapp/oauth2/funkwhale"
summary: "A list of redirect uris, separated by spaces"
description: "A list of redirect uris, separated by spaces"
scopes:
type: "string"
summary: "A list of scopes requested by your app, separated by spaces"
description: "A list of scopes requested by your app, separated by spaces"
example: "read write:playlists write:favorites"
/api/v1/oauth/token/:
post:
@ -244,6 +254,7 @@ paths:
security: []
responses:
200:
$ref: "#/components/responses/200"
/api/v1/auth/registration/:
post:
@ -259,6 +270,11 @@ paths:
application/json:
schema:
type: "object"
required:
- username
- email
- password1
- password2
properties:
username:
type: "string"
@ -269,7 +285,6 @@ paths:
invitation:
type: "string"
example: "INVITECODE"
required: false
description: An invitation code, required if signups are closed on the instance.
password1:
type: "string"
@ -280,7 +295,7 @@ paths:
example: "passw0rd"
responses:
201:
$ref: "#/responses/201"
$ref: "#/components/responses/201"
/api/v1/auth/password/reset/:
post:
summary: Request a password reset
@ -301,7 +316,7 @@ paths:
format: "email"
responses:
200:
$ref: "#/responses/200"
$ref: "#/components/responses/200"
/api/v1/users/me/:
get:
summary: Retrive profile information
@ -312,6 +327,7 @@ paths:
responses:
200:
description: ""
content:
application/json:
schema:
@ -335,6 +351,7 @@ paths:
description: "The current password of the account"
responses:
200:
description: ""
content:
application/json:
schema:
@ -359,6 +376,7 @@ paths:
description: "The current password of the account"
responses:
200:
description: ""
content:
application/json:
schema:
@ -372,6 +390,7 @@ paths:
responses:
200:
description: ""
content:
application/json:
schema:
@ -388,18 +407,7 @@ paths:
parameters:
- $ref: "./api/parameters.yml#/Search"
- allOf:
- $ref: "./api/parameters.yml#/Ordering"
- default: "-creation_date"
schema:
required: false
type: "string"
example: "creation_date"
enum:
- creation_date
- id
- name
- random
- $ref: "./api/parameters.yml#/ArtistOrdering"
- $ref: "./api/parameters.yml#/Playable"
- $ref: "./api/parameters.yml#/HasAlbums"
- $ref: "./api/parameters.yml#/Library"
@ -410,6 +418,7 @@ paths:
- $ref: "./api/parameters.yml#/ContentCategory"
responses:
200:
description: ""
content:
application/json:
schema:
@ -434,11 +443,13 @@ paths:
- "Library and metadata"
responses:
200:
description: ""
content:
application/json:
schema:
$ref: "./api/definitions.yml#/Artist"
404:
description: "Not Found"
content:
application/json:
schema:
@ -458,11 +469,13 @@ paths:
- "Library and metadata"
responses:
200:
description: ""
content:
application/json:
schema:
$ref: "./api/definitions.yml#/LibraryPage"
404:
description: "Not Found"
content:
application/json:
schema:
@ -478,28 +491,16 @@ paths:
- oauth2:
- "read:libraries"
parameters:
- $ref: "./api/parameters.yml#/Search"
- name: "artist"
in: "query"
default: null
required: false
description: "Only include albums by the requested artist"
schema:
required: false
nullable: true
type: "integer"
format: "int64"
- allOf:
- $ref: "./api/parameters.yml#/Ordering"
- default: "-creation_date"
schema:
required: false
type: "string"
example: "creation_date"
enum:
- creation_date
- release_date
- title
- random
- $ref: "./api/parameters.yml#/AlbumOrdering"
- $ref: "./api/parameters.yml#/Library"
- $ref: "./api/parameters.yml#/Playable"
- $ref: "./api/parameters.yml#/PageNumber"
@ -510,6 +511,7 @@ paths:
responses:
200:
description: ""
content:
application/json:
schema:
@ -535,11 +537,13 @@ paths:
- "Library and metadata"
responses:
200:
description: ""
content:
application/json:
schema:
$ref: "./api/definitions.yml#/Album"
404:
description: "Not Found"
content:
application/json:
schema:
@ -560,11 +564,13 @@ paths:
- "Library and metadata"
responses:
200:
description: ""
content:
application/json:
schema:
$ref: "./api/definitions.yml#/LibraryPage"
404:
description: "Not Found"
content:
application/json:
schema:
@ -584,47 +590,36 @@ paths:
- $ref: "./api/parameters.yml#/Search"
- name: "artist"
in: "query"
default: null
required: false
description: "Only include tracks by the requested artist"
schema:
required: false
nullable: true
type: "integer"
format: "int64"
- name: "favorites"
in: "query"
default: null
required: false
description: "filter/exclude tracks favorited by the current user"
schema:
required: false
nullable: true
type: "boolean"
- name: "album"
in: "query"
default: null
required: false
description: "Only include tracks from the requested album"
schema:
required: false
nullable: true
type: "integer"
format: "int64"
- name: "license"
in: "query"
description: "Only include tracks with the given license"
default: null
required: false
schema:
example: "cc-by-sa-4.0"
required: false
nullable: true
type: "string"
- allOf:
- $ref: "./api/parameters.yml#/Ordering"
- default: "-creation_date"
schema:
required: false
type: "string"
example: "creation_date"
enum:
- creation_date
- release_date
- title
- random
- $ref: "./api/parameters.yml#/TrackOrdering"
- $ref: "./api/parameters.yml#/Library"
- $ref: "./api/parameters.yml#/Playable"
- $ref: "./api/parameters.yml#/PageNumber"
@ -634,6 +629,7 @@ paths:
responses:
200:
description: ""
content:
application/json:
schema:
@ -659,11 +655,13 @@ paths:
- "Library and metadata"
responses:
200:
description: ""
content:
application/json:
schema:
$ref: "./api/definitions.yml#/Track"
404:
description: "Not Found"
content:
application/json:
schema:
@ -683,11 +681,13 @@ paths:
- "Library and metadata"
responses:
200:
description: ""
content:
application/json:
schema:
$ref: "./api/definitions.yml#/LibraryPage"
404:
description: "Not Found"
content:
application/json:
schema:
@ -727,8 +727,9 @@ paths:
- name: upload
in: query
required: false
summary: An upload uuid
description: |
An upload uuid
If specified, will return the audio for the given upload uuid.
This is useful for tracks that have multiple uploads available.
@ -751,13 +752,15 @@ paths:
- "Library and metadata"
responses:
200:
description: ""
content:
'*/*':
description: "Audio file, as binary data"
schema:
description: "Audio file, as binary data"
type: string
format: binary
404:
description: "Not Found"
content:
application/json:
schema:
@ -776,6 +779,7 @@ paths:
- $ref: "./api/parameters.yml#/PageSize"
responses:
200:
description: ""
content:
application/json:
schema:
@ -807,11 +811,13 @@ paths:
- "Library and metadata"
responses:
200:
description: ""
content:
application/json:
schema:
$ref: "./api/definitions.yml#/License"
404:
description: "Not Found"
content:
application/json:
schema:
@ -829,6 +835,7 @@ paths:
- $ref: "./api/parameters.yml#/Scope"
responses:
200:
description: ""
content:
application/json:
schema:
@ -847,9 +854,9 @@ paths:
Create a new library
responses:
201:
$ref: "#/responses/201"
$ref: "#/components/responses/201"
400:
$ref: "#/responses/400"
$ref: "#/components/responses/400"
requestBody:
required: true
content:
@ -871,6 +878,7 @@ paths:
- "Uploads and audio content"
responses:
200:
description: ""
content:
application/json:
schema:
@ -887,6 +895,7 @@ paths:
$ref: "./api/definitions.yml#/OwnedLibraryCreate"
responses:
201:
description: ""
content:
application/json:
schema:
@ -900,7 +909,7 @@ paths:
- "Uploads and audio content"
responses:
204:
$ref: "#/responses/204"
$ref: "#/components/responses/204"
/api/v1/channels/:
get:
@ -908,17 +917,6 @@ paths:
tags:
- "Channels and subscriptions"
parameters:
- allOf:
- $ref: "./api/parameters.yml#/Ordering"
- default: "-creation_date"
schema:
required: false
type: "string"
example: "creation_date"
enum:
- creation_date
- modification_date
- random
- $ref: "./api/parameters.yml#/PageNumber"
- $ref: "./api/parameters.yml#/PageSize"
- $ref: "./api/parameters.yml#/Scope"
@ -930,6 +928,7 @@ paths:
responses:
200:
description: ""
content:
application/json:
schema:
@ -947,9 +946,9 @@ paths:
- "Channels and subscriptions"
responses:
201:
$ref: "#/responses/201"
$ref: "#/components/responses/201"
400:
$ref: "#/responses/400"
$ref: "#/components/responses/400"
requestBody:
required: true
content:
@ -959,14 +958,14 @@ paths:
/api/v1/channels/metadata-choices:
summary: List metadata (locales, itunes categories) for creating and editing channels.
tags:
- "Channels and subscriptions"
description: "Channels and subscriptions"
get:
summary: List channels metadata options
tags:
- "Channels and subscriptions"
responses:
200:
description: ""
content:
application/json:
schema:
@ -1018,6 +1017,7 @@ paths:
- "Channels and subscriptions"
responses:
200:
description: ""
content:
application/json:
schema:
@ -1034,6 +1034,7 @@ paths:
$ref: "./api/definitions.yml#/ChannelUpdate"
responses:
201:
description: ""
content:
application/json:
schema:
@ -1047,7 +1048,7 @@ paths:
- "Channels and subscriptions"
responses:
204:
$ref: "#/responses/204"
$ref: "#/components/responses/204"
/api/v1/channels/rss-suscribe/:
post:
@ -1068,6 +1069,7 @@ paths:
- "Channels and subscriptions"
responses:
201:
description: ""
content:
application/json:
schema:
@ -1087,8 +1089,9 @@ paths:
- "Channels and subscriptions"
responses:
200:
description: ""
content:
application/rss+xml:
application/rss+xml: {}
/api/v1/channels/{uuid}/subscribe/:
parameters:
@ -1104,6 +1107,7 @@ paths:
- "Channels and subscriptions"
responses:
201:
description: ""
content:
application/json:
schema:
@ -1123,6 +1127,7 @@ paths:
- "Channels and subscriptions"
responses:
204:
$ref: "#/components/responses/204"
/api/v1/uploads/:
get:
@ -1137,6 +1142,7 @@ paths:
- $ref: "./api/parameters.yml#/Scope"
responses:
200:
description: ""
content:
application/json:
schema:
@ -1156,15 +1162,21 @@ paths:
according to the library visibility and followers.
responses:
201:
$ref: "#/responses/201"
$ref: "#/components/responses/201"
400:
$ref: "#/responses/400"
$ref: "#/components/responses/400"
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- library
- import_reference
- source
- audio_file
- import_status
properties:
library:
type: string
@ -1187,10 +1199,8 @@ paths:
- "draft"
- "pending"
import_metadata:
required: false
$ref: "./api/definitions.yml#/ImportMetadata"
/api/v1/subscriptions/{uuid}/:
parameters:
- name: uuid
@ -1205,6 +1215,7 @@ paths:
- "Channels and subscriptions"
responses:
200:
description: ""
content:
application/json:
schema:
@ -1217,6 +1228,7 @@ paths:
- "Channels and subscriptions"
responses:
200:
description: ""
content:
application/json:
schema:
@ -1236,6 +1248,7 @@ paths:
- "Channels and subscriptions"
responses:
200:
description: ""
content:
application/json:
schema:
@ -1260,6 +1273,7 @@ paths:
- "Uploads and audio content"
responses:
200:
description: ""
content:
application/json:
schema:
@ -1278,6 +1292,7 @@ paths:
- "Uploads and audio content"
responses:
200:
description: ""
content:
application/json:
schema:
@ -1291,7 +1306,7 @@ paths:
- "Uploads and audio content"
responses:
204:
$ref: "#/responses/204"
$ref: "#/components/responses/204"
/api/v1/uploads/{uuid}/audio-file-metadata:
parameters:
@ -1307,11 +1322,12 @@ paths:
- "Uploads and audio content"
responses:
200:
description: ""
content:
application/json:
schema:
type: "object"
properties: []
properties: {}
/api/v1/favorites/tracks/:
get:
@ -1325,6 +1341,7 @@ paths:
responses:
200:
description: ""
content:
application/json:
schema:
@ -1353,6 +1370,7 @@ paths:
example: 98
responses:
201:
description: ""
content:
application/json:
schema:
@ -1386,7 +1404,7 @@ paths:
example: 98
responses:
204:
$ref: "#/responses/204"
$ref: "#/components/responses/204"
#################
@ -1405,6 +1423,7 @@ paths:
responses:
200:
description: ""
content:
application/json:
schema:
@ -1433,6 +1452,7 @@ paths:
example: 98
responses:
201:
description: ""
content:
application/json:
schema:
@ -1452,9 +1472,9 @@ paths:
- $ref: "./api/parameters.yml#/Search"
responses:
200:
$ref: "#/responses/200"
$ref: "#/components/responses/200"
400:
$ref: "#/responses/400"
$ref: "#/components/responses/400"
/api/v1/instance/settings:
get:
@ -1464,6 +1484,7 @@ paths:
Retrieve pod-level configuration such as description or max playlist size
responses:
200:
description: ""
content:
application/json:
schema:
@ -1510,9 +1531,9 @@ paths:
Upload a new file as an attachment that can be later associated with other objects.
responses:
201:
$ref: "#/responses/201"
$ref: "#/components/responses/201"
400:
$ref: "#/responses/400"
$ref: "#/components/responses/400"
requestBody:
required: true
content:
@ -1538,6 +1559,7 @@ paths:
- "Other"
responses:
200:
description: ""
content:
application/json:
schema:
@ -1548,7 +1570,7 @@ paths:
- "Other"
responses:
204:
$ref: "#/responses/204"
$ref: "#/components/responses/204"
/api/v1/playlists/:
get:
@ -1557,18 +1579,7 @@ paths:
- "Content curation"
parameters:
- $ref: "./api/parameters.yml#/Search"
- allOf:
- $ref: "./api/parameters.yml#/Ordering"
- default: "-creation_date"
schema:
required: false
type: "string"
example: "creation_date"
enum:
- creation_date
- modification_date
- id
- name
- $ref: "./api/parameters.yml#/PlaylistOrdering"
- in: query
name: artist
description: Restrict to playlists containing tracks from the given artist
@ -1592,6 +1603,7 @@ paths:
- $ref: "./api/parameters.yml#/PageSize"
responses:
200:
description: ""
content:
application/json:
schema:
@ -1609,9 +1621,9 @@ paths:
description: Create a new playlist
responses:
201:
$ref: "#/responses/201"
$ref: "#/components/responses/201"
400:
$ref: "#/responses/400"
$ref: "#/components/responses/400"
requestBody:
required: true
content:
@ -1632,6 +1644,7 @@ paths:
- "Content curation"
responses:
200:
description: ""
content:
application/json:
schema:
@ -1648,6 +1661,7 @@ paths:
$ref: "./api/definitions.yml#/PlaylistCreate"
responses:
201:
description: ""
content:
application/json:
schema:
@ -1658,7 +1672,7 @@ paths:
- "Content curation"
responses:
204:
$ref: "#/responses/204"
$ref: "#/components/responses/204"
/api/v1/playlists/{id}/tracks:
parameters:
- name: id
@ -1673,6 +1687,7 @@ paths:
- "Content curation"
responses:
200:
description: ""
content:
application/json:
schema:
@ -1718,6 +1733,7 @@ paths:
multiple time in the playlist
responses:
201:
description: ""
content:
application/json:
schema:
@ -1759,6 +1775,7 @@ paths:
responses:
204:
$ref: "#/components/responses/204"
/api/v1/playlists/{id}/remove:
parameters:
- name: id
@ -1785,7 +1802,7 @@ paths:
responses:
204:
$ref: "#/components/responses/204"
/api/v1/playlists/{id}/clear:
parameters:
- name: id
@ -1800,6 +1817,7 @@ paths:
- "Content curation"
responses:
204:
$ref: "#/components/responses/204"
/api/v1/radios/sessions:
post:
tags:
@ -1807,9 +1825,9 @@ paths:
description: Start a new radio session
responses:
201:
$ref: "#/responses/201"
$ref: "#/components/responses/201"
400:
$ref: "#/responses/400"
$ref: "#/components/responses/400"
requestBody:
required: true
content:
@ -1823,21 +1841,12 @@ paths:
description: Get a new track for a radio session
responses:
201:
$ref: "#/responses/201"
$ref: "#/components/responses/201"
400:
$ref: "#/responses/400"
$ref: "#/components/responses/400"
requestBody:
required: true
content:
application/json:
schema:
$ref: "./api/definitions.yml#/Track"
responses:
200:
description: Success
201:
description: Successfully created
204:
description: Successfully deleted
400:
description: Bad request