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

105
docs/api/parameters.yml
View File

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

291
docs/swagger.yml
View File

@ -16,20 +16,20 @@ info:
OAuth Authentication OAuth Authentication
-------------------- --------------------
You can register your own OAuth app using the `/api/v1/oauth/apps/` endpoint. Proceed to the standard OAuth flow afterwards: You can register your own OAuth app using the `/api/v1/oauth/apps/` endpoint. Proceed to the standard OAuth flow afterwards:
- Our authorize URL is at `/authorize` - Our authorize URL is at `/authorize`
- Our token acquisition and refresh URL is at `/api/v1/oauth/token` - Our token acquisition and refresh URL is at `/api/v1/oauth/token`
- The list of supported scopes is available by clicking the `Authorize` button in the Swagger UI documentation - The list of supported scopes is available by clicking the `Authorize` button in the Swagger UI documentation
- Use `urn:ietf:wg:oauth:2.0:oob` as your redirect URI if you want the user to get a copy-pastable authorization code - Use `urn:ietf:wg:oauth:2.0:oob` as your redirect URI if you want the user to get a copy-pastable authorization code
- At the moment, endpoints that deal with admin or moderator-level content are not accessible via OAuth, only through the Web UI - At the moment, endpoints that deal with admin or moderator-level content are not accessible via OAuth, only through the Web UI
You can use our demo server at `https://demo.funkwhale.audio` for testing purposes. You can use our demo server at `https://demo.funkwhale.audio` for testing purposes.
Application token authentication Application token authentication
-------------------------------- --------------------------------
If using OAuth isn't practical and you have an account on the Funkwhale pod, you can create an application by visiting `/settings`. If using OAuth isn't practical and you have an account on the Funkwhale pod, you can create an application by visiting `/settings`.
Once the application is created, you can authenticate using its access token in the `Authorization` header, like this: `Authorization: Bearer <token>`. Once the application is created, you can authenticate using its access token in the `Authorization` header, like this: `Authorization: Bearer <token>`.
@ -134,6 +134,15 @@ servers:
default: 'https' default: 'https'
components: components:
responses:
200:
description: Success
201:
description: Successfully created
204:
description: Successfully deleted
400:
description: Bad request
securitySchemes: securitySchemes:
oauth2: oauth2:
type: oauth2 type: oauth2
@ -210,6 +219,7 @@ paths:
security: [] security: []
responses: responses:
201: 201:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -226,14 +236,14 @@ paths:
name: name:
type: "string" type: "string"
example: "My Awesome Funkwhale Client" example: "My Awesome Funkwhale Client"
summary: "A human readable name for your app" description: "A human readable name for your app"
redirect_uris: redirect_uris:
type: "string" type: "string"
example: "https://myapp/oauth2/funkwhale" example: "https://myapp/oauth2/funkwhale"
summary: "A list of redirect uris, separated by spaces" description: "A list of redirect uris, separated by spaces"
scopes: scopes:
type: "string" 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" example: "read write:playlists write:favorites"
/api/v1/oauth/token/: /api/v1/oauth/token/:
post: post:
@ -244,6 +254,7 @@ paths:
security: [] security: []
responses: responses:
200: 200:
$ref: "#/components/responses/200"
/api/v1/auth/registration/: /api/v1/auth/registration/:
post: post:
@ -259,6 +270,11 @@ paths:
application/json: application/json:
schema: schema:
type: "object" type: "object"
required:
- username
- email
- password1
- password2
properties: properties:
username: username:
type: "string" type: "string"
@ -269,7 +285,6 @@ paths:
invitation: invitation:
type: "string" type: "string"
example: "INVITECODE" example: "INVITECODE"
required: false
description: An invitation code, required if signups are closed on the instance. description: An invitation code, required if signups are closed on the instance.
password1: password1:
type: "string" type: "string"
@ -280,7 +295,7 @@ paths:
example: "passw0rd" example: "passw0rd"
responses: responses:
201: 201:
$ref: "#/responses/201" $ref: "#/components/responses/201"
/api/v1/auth/password/reset/: /api/v1/auth/password/reset/:
post: post:
summary: Request a password reset summary: Request a password reset
@ -301,7 +316,7 @@ paths:
format: "email" format: "email"
responses: responses:
200: 200:
$ref: "#/responses/200" $ref: "#/components/responses/200"
/api/v1/users/me/: /api/v1/users/me/:
get: get:
summary: Retrive profile information summary: Retrive profile information
@ -312,6 +327,7 @@ paths:
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -335,6 +351,7 @@ paths:
description: "The current password of the account" description: "The current password of the account"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -359,6 +376,7 @@ paths:
description: "The current password of the account" description: "The current password of the account"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -372,6 +390,7 @@ paths:
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -384,22 +403,11 @@ paths:
- "Library and metadata" - "Library and metadata"
security: security:
- oauth2: - oauth2:
- "read:libraries" - "read:libraries"
parameters: parameters:
- $ref: "./api/parameters.yml#/Search" - $ref: "./api/parameters.yml#/Search"
- allOf: - $ref: "./api/parameters.yml#/ArtistOrdering"
- $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#/Playable" - $ref: "./api/parameters.yml#/Playable"
- $ref: "./api/parameters.yml#/HasAlbums" - $ref: "./api/parameters.yml#/HasAlbums"
- $ref: "./api/parameters.yml#/Library" - $ref: "./api/parameters.yml#/Library"
@ -410,6 +418,7 @@ paths:
- $ref: "./api/parameters.yml#/ContentCategory" - $ref: "./api/parameters.yml#/ContentCategory"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -429,16 +438,18 @@ paths:
- $ref: "./api/parameters.yml#/Refresh" - $ref: "./api/parameters.yml#/Refresh"
security: security:
- oauth2: - oauth2:
- "read:libraries" - "read:libraries"
tags: tags:
- "Library and metadata" - "Library and metadata"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
$ref: "./api/definitions.yml#/Artist" $ref: "./api/definitions.yml#/Artist"
404: 404:
description: "Not Found"
content: content:
application/json: application/json:
schema: schema:
@ -448,7 +459,7 @@ paths:
summary: List available user libraries containing work from this artist summary: List available user libraries containing work from this artist
security: security:
- oauth2: - oauth2:
- "read:libraries" - "read:libraries"
parameters: parameters:
- $ref: "./api/parameters.yml#/ObjectId" - $ref: "./api/parameters.yml#/ObjectId"
- $ref: "./api/parameters.yml#/PageNumber" - $ref: "./api/parameters.yml#/PageNumber"
@ -458,11 +469,13 @@ paths:
- "Library and metadata" - "Library and metadata"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
$ref: "./api/definitions.yml#/LibraryPage" $ref: "./api/definitions.yml#/LibraryPage"
404: 404:
description: "Not Found"
content: content:
application/json: application/json:
schema: schema:
@ -476,30 +489,18 @@ paths:
security: security:
- oauth2: - oauth2:
- "read:libraries" - "read:libraries"
parameters: parameters:
- $ref: "./api/parameters.yml#/Search" - $ref: "./api/parameters.yml#/Search"
- name: "artist" - name: "artist"
in: "query" in: "query"
default: null required: false
description: "Only include albums by the requested artist" description: "Only include albums by the requested artist"
schema: schema:
required: false nullable: true
type: "integer" type: "integer"
format: "int64" format: "int64"
- allOf: - $ref: "./api/parameters.yml#/AlbumOrdering"
- $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#/Library" - $ref: "./api/parameters.yml#/Library"
- $ref: "./api/parameters.yml#/Playable" - $ref: "./api/parameters.yml#/Playable"
- $ref: "./api/parameters.yml#/PageNumber" - $ref: "./api/parameters.yml#/PageNumber"
@ -510,6 +511,7 @@ paths:
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -530,16 +532,18 @@ paths:
security: security:
- oauth2: - oauth2:
- "read:libraries" - "read:libraries"
tags: tags:
- "Library and metadata" - "Library and metadata"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
$ref: "./api/definitions.yml#/Album" $ref: "./api/definitions.yml#/Album"
404: 404:
description: "Not Found"
content: content:
application/json: application/json:
schema: schema:
@ -555,16 +559,18 @@ paths:
security: security:
- oauth2: - oauth2:
- "read:libraries" - "read:libraries"
tags: tags:
- "Library and metadata" - "Library and metadata"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
$ref: "./api/definitions.yml#/LibraryPage" $ref: "./api/definitions.yml#/LibraryPage"
404: 404:
description: "Not Found"
content: content:
application/json: application/json:
schema: schema:
@ -578,53 +584,42 @@ paths:
security: security:
- oauth2: - oauth2:
- "read:libraries" - "read:libraries"
parameters: parameters:
- $ref: "./api/parameters.yml#/Search" - $ref: "./api/parameters.yml#/Search"
- name: "artist" - name: "artist"
in: "query" in: "query"
default: null required: false
description: "Only include tracks by the requested artist" description: "Only include tracks by the requested artist"
schema: schema:
required: false nullable: true
type: "integer" type: "integer"
format: "int64" format: "int64"
- name: "favorites" - name: "favorites"
in: "query" in: "query"
default: null required: false
description: "filter/exclude tracks favorited by the current user" description: "filter/exclude tracks favorited by the current user"
schema: schema:
required: false nullable: true
type: "boolean" type: "boolean"
- name: "album" - name: "album"
in: "query" in: "query"
default: null required: false
description: "Only include tracks from the requested album" description: "Only include tracks from the requested album"
schema: schema:
required: false nullable: true
type: "integer" type: "integer"
format: "int64" format: "int64"
- name: "license" - name: "license"
in: "query" in: "query"
description: "Only include tracks with the given license" description: "Only include tracks with the given license"
default: null required: false
schema: schema:
example: "cc-by-sa-4.0" example: "cc-by-sa-4.0"
required: false nullable: true
type: "string" type: "string"
- allOf: - $ref: "./api/parameters.yml#/TrackOrdering"
- $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#/Library" - $ref: "./api/parameters.yml#/Library"
- $ref: "./api/parameters.yml#/Playable" - $ref: "./api/parameters.yml#/Playable"
- $ref: "./api/parameters.yml#/PageNumber" - $ref: "./api/parameters.yml#/PageNumber"
@ -634,6 +629,7 @@ paths:
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -654,16 +650,18 @@ paths:
security: security:
- oauth2: - oauth2:
- "read:libraries" - "read:libraries"
tags: tags:
- "Library and metadata" - "Library and metadata"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
$ref: "./api/definitions.yml#/Track" $ref: "./api/definitions.yml#/Track"
404: 404:
description: "Not Found"
content: content:
application/json: application/json:
schema: schema:
@ -678,16 +676,18 @@ paths:
- $ref: "./api/parameters.yml#/PageSize" - $ref: "./api/parameters.yml#/PageSize"
security: security:
- oauth2: - oauth2:
- "read:libraries" - "read:libraries"
tags: tags:
- "Library and metadata" - "Library and metadata"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
$ref: "./api/definitions.yml#/LibraryPage" $ref: "./api/definitions.yml#/LibraryPage"
404: 404:
description: "Not Found"
content: content:
application/json: application/json:
schema: schema:
@ -727,8 +727,9 @@ paths:
- name: upload - name: upload
in: query in: query
required: false required: false
summary: An upload uuid
description: | description: |
An upload uuid
If specified, will return the audio for the given upload uuid. If specified, will return the audio for the given upload uuid.
This is useful for tracks that have multiple uploads available. This is useful for tracks that have multiple uploads available.
@ -751,13 +752,15 @@ paths:
- "Library and metadata" - "Library and metadata"
responses: responses:
200: 200:
description: ""
content: content:
'*/*': '*/*':
description: "Audio file, as binary data"
schema: schema:
description: "Audio file, as binary data"
type: string type: string
format: binary format: binary
404: 404:
description: "Not Found"
content: content:
application/json: application/json:
schema: schema:
@ -768,7 +771,7 @@ paths:
summary: List licenses summary: List licenses
security: security:
- oauth2: - oauth2:
- "read:libraries" - "read:libraries"
tags: tags:
- "Library and metadata" - "Library and metadata"
parameters: parameters:
@ -776,6 +779,7 @@ paths:
- $ref: "./api/parameters.yml#/PageSize" - $ref: "./api/parameters.yml#/PageSize"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -793,7 +797,7 @@ paths:
summary: Retrieve a single license summary: Retrieve a single license
security: security:
- oauth2: - oauth2:
- "read:libraries" - "read:libraries"
parameters: parameters:
- name: code - name: code
in: path in: path
@ -807,11 +811,13 @@ paths:
- "Library and metadata" - "Library and metadata"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
$ref: "./api/definitions.yml#/License" $ref: "./api/definitions.yml#/License"
404: 404:
description: "Not Found"
content: content:
application/json: application/json:
schema: schema:
@ -829,6 +835,7 @@ paths:
- $ref: "./api/parameters.yml#/Scope" - $ref: "./api/parameters.yml#/Scope"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -847,9 +854,9 @@ paths:
Create a new library Create a new library
responses: responses:
201: 201:
$ref: "#/responses/201" $ref: "#/components/responses/201"
400: 400:
$ref: "#/responses/400" $ref: "#/components/responses/400"
requestBody: requestBody:
required: true required: true
content: content:
@ -871,6 +878,7 @@ paths:
- "Uploads and audio content" - "Uploads and audio content"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -887,6 +895,7 @@ paths:
$ref: "./api/definitions.yml#/OwnedLibraryCreate" $ref: "./api/definitions.yml#/OwnedLibraryCreate"
responses: responses:
201: 201:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -900,7 +909,7 @@ paths:
- "Uploads and audio content" - "Uploads and audio content"
responses: responses:
204: 204:
$ref: "#/responses/204" $ref: "#/components/responses/204"
/api/v1/channels/: /api/v1/channels/:
get: get:
@ -908,17 +917,6 @@ paths:
tags: tags:
- "Channels and subscriptions" - "Channels and subscriptions"
parameters: 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#/PageNumber"
- $ref: "./api/parameters.yml#/PageSize" - $ref: "./api/parameters.yml#/PageSize"
- $ref: "./api/parameters.yml#/Scope" - $ref: "./api/parameters.yml#/Scope"
@ -930,6 +928,7 @@ paths:
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -947,9 +946,9 @@ paths:
- "Channels and subscriptions" - "Channels and subscriptions"
responses: responses:
201: 201:
$ref: "#/responses/201" $ref: "#/components/responses/201"
400: 400:
$ref: "#/responses/400" $ref: "#/components/responses/400"
requestBody: requestBody:
required: true required: true
content: content:
@ -959,14 +958,14 @@ paths:
/api/v1/channels/metadata-choices: /api/v1/channels/metadata-choices:
summary: List metadata (locales, itunes categories) for creating and editing channels. summary: List metadata (locales, itunes categories) for creating and editing channels.
tags: description: "Channels and subscriptions"
- "Channels and subscriptions"
get: get:
summary: List channels metadata options summary: List channels metadata options
tags: tags:
- "Channels and subscriptions" - "Channels and subscriptions"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1018,6 +1017,7 @@ paths:
- "Channels and subscriptions" - "Channels and subscriptions"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1034,6 +1034,7 @@ paths:
$ref: "./api/definitions.yml#/ChannelUpdate" $ref: "./api/definitions.yml#/ChannelUpdate"
responses: responses:
201: 201:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1047,7 +1048,7 @@ paths:
- "Channels and subscriptions" - "Channels and subscriptions"
responses: responses:
204: 204:
$ref: "#/responses/204" $ref: "#/components/responses/204"
/api/v1/channels/rss-suscribe/: /api/v1/channels/rss-suscribe/:
post: post:
@ -1068,6 +1069,7 @@ paths:
- "Channels and subscriptions" - "Channels and subscriptions"
responses: responses:
201: 201:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1087,8 +1089,9 @@ paths:
- "Channels and subscriptions" - "Channels and subscriptions"
responses: responses:
200: 200:
description: ""
content: content:
application/rss+xml: application/rss+xml: {}
/api/v1/channels/{uuid}/subscribe/: /api/v1/channels/{uuid}/subscribe/:
parameters: parameters:
@ -1104,6 +1107,7 @@ paths:
- "Channels and subscriptions" - "Channels and subscriptions"
responses: responses:
201: 201:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1123,6 +1127,7 @@ paths:
- "Channels and subscriptions" - "Channels and subscriptions"
responses: responses:
204: 204:
$ref: "#/components/responses/204"
/api/v1/uploads/: /api/v1/uploads/:
get: get:
@ -1137,6 +1142,7 @@ paths:
- $ref: "./api/parameters.yml#/Scope" - $ref: "./api/parameters.yml#/Scope"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1156,15 +1162,21 @@ paths:
according to the library visibility and followers. according to the library visibility and followers.
responses: responses:
201: 201:
$ref: "#/responses/201" $ref: "#/components/responses/201"
400: 400:
$ref: "#/responses/400" $ref: "#/components/responses/400"
requestBody: requestBody:
required: true required: true
content: content:
multipart/form-data: multipart/form-data:
schema: schema:
type: object type: object
required:
- library
- import_reference
- source
- audio_file
- import_status
properties: properties:
library: library:
type: string type: string
@ -1184,13 +1196,11 @@ paths:
description: "Setting import_status to draft will prevent processing, but allow further modifications to audio and metadata. Once ready, use the PATCH method to set import_status to pending. Default to `pending` if unspecified." description: "Setting import_status to draft will prevent processing, but allow further modifications to audio and metadata. Once ready, use the PATCH method to set import_status to pending. Default to `pending` if unspecified."
default: "pending" default: "pending"
enum: enum:
- "draft" - "draft"
- "pending" - "pending"
import_metadata: import_metadata:
required: false
$ref: "./api/definitions.yml#/ImportMetadata" $ref: "./api/definitions.yml#/ImportMetadata"
/api/v1/subscriptions/{uuid}/: /api/v1/subscriptions/{uuid}/:
parameters: parameters:
- name: uuid - name: uuid
@ -1205,6 +1215,7 @@ paths:
- "Channels and subscriptions" - "Channels and subscriptions"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1217,6 +1228,7 @@ paths:
- "Channels and subscriptions" - "Channels and subscriptions"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1236,6 +1248,7 @@ paths:
- "Channels and subscriptions" - "Channels and subscriptions"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1260,6 +1273,7 @@ paths:
- "Uploads and audio content" - "Uploads and audio content"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1278,6 +1292,7 @@ paths:
- "Uploads and audio content" - "Uploads and audio content"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1291,7 +1306,7 @@ paths:
- "Uploads and audio content" - "Uploads and audio content"
responses: responses:
204: 204:
$ref: "#/responses/204" $ref: "#/components/responses/204"
/api/v1/uploads/{uuid}/audio-file-metadata: /api/v1/uploads/{uuid}/audio-file-metadata:
parameters: parameters:
@ -1307,11 +1322,12 @@ paths:
- "Uploads and audio content" - "Uploads and audio content"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
type: "object" type: "object"
properties: [] properties: {}
/api/v1/favorites/tracks/: /api/v1/favorites/tracks/:
get: get:
@ -1325,6 +1341,7 @@ paths:
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1353,6 +1370,7 @@ paths:
example: 98 example: 98
responses: responses:
201: 201:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1386,9 +1404,9 @@ paths:
example: 98 example: 98
responses: responses:
204: 204:
$ref: "#/responses/204" $ref: "#/components/responses/204"
################# #################
# User activity # # User activity #
################# #################
@ -1405,6 +1423,7 @@ paths:
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1433,11 +1452,12 @@ paths:
example: 98 example: 98
responses: responses:
201: 201:
description: ""
content: content:
application/json: application/json:
schema: schema:
$ref: "./api/definitions.yml#/ListeningCreate" $ref: "./api/definitions.yml#/ListeningCreate"
########## ##########
# Others # # Others #
########## ##########
@ -1452,10 +1472,10 @@ paths:
- $ref: "./api/parameters.yml#/Search" - $ref: "./api/parameters.yml#/Search"
responses: responses:
200: 200:
$ref: "#/responses/200" $ref: "#/components/responses/200"
400: 400:
$ref: "#/responses/400" $ref: "#/components/responses/400"
/api/v1/instance/settings: /api/v1/instance/settings:
get: get:
tags: tags:
@ -1464,6 +1484,7 @@ paths:
Retrieve pod-level configuration such as description or max playlist size Retrieve pod-level configuration such as description or max playlist size
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1500,7 +1521,7 @@ paths:
input_type: input_type:
type: string type: string
description: "Input type of the setting" description: "Input type of the setting"
/api/v1/attachments/: /api/v1/attachments/:
post: post:
@ -1510,9 +1531,9 @@ paths:
Upload a new file as an attachment that can be later associated with other objects. Upload a new file as an attachment that can be later associated with other objects.
responses: responses:
201: 201:
$ref: "#/responses/201" $ref: "#/components/responses/201"
400: 400:
$ref: "#/responses/400" $ref: "#/components/responses/400"
requestBody: requestBody:
required: true required: true
content: content:
@ -1538,6 +1559,7 @@ paths:
- "Other" - "Other"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1548,7 +1570,7 @@ paths:
- "Other" - "Other"
responses: responses:
204: 204:
$ref: "#/responses/204" $ref: "#/components/responses/204"
/api/v1/playlists/: /api/v1/playlists/:
get: get:
@ -1557,18 +1579,7 @@ paths:
- "Content curation" - "Content curation"
parameters: parameters:
- $ref: "./api/parameters.yml#/Search" - $ref: "./api/parameters.yml#/Search"
- allOf: - $ref: "./api/parameters.yml#/PlaylistOrdering"
- $ref: "./api/parameters.yml#/Ordering"
- default: "-creation_date"
schema:
required: false
type: "string"
example: "creation_date"
enum:
- creation_date
- modification_date
- id
- name
- in: query - in: query
name: artist name: artist
description: Restrict to playlists containing tracks from the given artist description: Restrict to playlists containing tracks from the given artist
@ -1592,6 +1603,7 @@ paths:
- $ref: "./api/parameters.yml#/PageSize" - $ref: "./api/parameters.yml#/PageSize"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1609,9 +1621,9 @@ paths:
description: Create a new playlist description: Create a new playlist
responses: responses:
201: 201:
$ref: "#/responses/201" $ref: "#/components/responses/201"
400: 400:
$ref: "#/responses/400" $ref: "#/components/responses/400"
requestBody: requestBody:
required: true required: true
content: content:
@ -1632,6 +1644,7 @@ paths:
- "Content curation" - "Content curation"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1648,6 +1661,7 @@ paths:
$ref: "./api/definitions.yml#/PlaylistCreate" $ref: "./api/definitions.yml#/PlaylistCreate"
responses: responses:
201: 201:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1658,7 +1672,7 @@ paths:
- "Content curation" - "Content curation"
responses: responses:
204: 204:
$ref: "#/responses/204" $ref: "#/components/responses/204"
/api/v1/playlists/{id}/tracks: /api/v1/playlists/{id}/tracks:
parameters: parameters:
- name: id - name: id
@ -1673,6 +1687,7 @@ paths:
- "Content curation" - "Content curation"
responses: responses:
200: 200:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1718,6 +1733,7 @@ paths:
multiple time in the playlist multiple time in the playlist
responses: responses:
201: 201:
description: ""
content: content:
application/json: application/json:
schema: schema:
@ -1756,9 +1772,10 @@ paths:
type: "integer" type: "integer"
format: "int64" format: "int64"
description: New index of the track description: New index of the track
responses: responses:
204: 204:
$ref: "#/components/responses/204"
/api/v1/playlists/{id}/remove: /api/v1/playlists/{id}/remove:
parameters: parameters:
- name: id - name: id
@ -1782,10 +1799,10 @@ paths:
type: "integer" type: "integer"
format: "int64" format: "int64"
description: Index of the track to remove description: Index of the track to remove
responses: responses:
204: 204:
$ref: "#/components/responses/204"
/api/v1/playlists/{id}/clear: /api/v1/playlists/{id}/clear:
parameters: parameters:
- name: id - name: id
@ -1800,6 +1817,7 @@ paths:
- "Content curation" - "Content curation"
responses: responses:
204: 204:
$ref: "#/components/responses/204"
/api/v1/radios/sessions: /api/v1/radios/sessions:
post: post:
tags: tags:
@ -1807,9 +1825,9 @@ paths:
description: Start a new radio session description: Start a new radio session
responses: responses:
201: 201:
$ref: "#/responses/201" $ref: "#/components/responses/201"
400: 400:
$ref: "#/responses/400" $ref: "#/components/responses/400"
requestBody: requestBody:
required: true required: true
content: content:
@ -1823,21 +1841,12 @@ paths:
description: Get a new track for a radio session description: Get a new track for a radio session
responses: responses:
201: 201:
$ref: "#/responses/201" $ref: "#/components/responses/201"
400: 400:
$ref: "#/responses/400" $ref: "#/components/responses/400"
requestBody: requestBody:
required: true required: true
content: content:
application/json: application/json:
schema: schema:
$ref: "./api/definitions.yml#/Track" $ref: "./api/definitions.yml#/Track"
responses:
200:
description: Success
201:
description: Successfully created
204:
description: Successfully deleted
400:
description: Bad request