Commit 1ab73704 authored by m-idler's avatar m-idler
Browse files

#1171 fix validity issues in openapi/swagger spec files

parent 08f54b1f
Pipeline #20477 failed with stage
in 9 seconds
......@@ -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"
......
ChannelOrdering:
- $ref: "#/Ordering"
- default: "-creation_date"
schema:
required: false
type: "string"
example: "-creation_date"
enum:
- creation_date
- artist__modification_date
$ref: "#/Ordering"
required: false
schema:
type: "string"
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.
required: false
schema:
required: false
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"
required: false
schema:
required: false
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"
required: false
schema:
required: false
type: array
collectionFormat: csv
items:
type: string
example:
- rock
- metal
\ No newline at end of file
- metal
......@@ -16,20 +16,20 @@ info:
OAuth Authentication
--------------------
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 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
- 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
You can use our demo server at `https://demo.funkwhale.audio` for testing purposes.
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`.
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'
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:
......@@ -384,22 +403,11 @@ paths:
- "Library and metadata"
security:
- oauth2:
- "read:libraries"
- "read:libraries"
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:
......@@ -429,16 +438,18 @@ paths:
- $ref: "./api/parameters.yml#/Refresh"
security:
- oauth2:
- "read:libraries"
- "read:libraries"
tags:
- "Library and metadata"
responses:
200:
description: ""
content:
application/json:
schema:
$ref: "./api/definitions.yml#/Artist"
404:
description: "Not Found"
content:
application/json:
schema:
......@@ -448,7 +459,7 @@ paths:
summary: List available user libraries containing work from this artist
security:
- oauth2:
- "read:libraries"
- "read:libraries"
parameters:
- $ref: "./api/parameters.yml#/ObjectId"
- $ref: "./api/parameters.yml#/PageNumber"
......@@ -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:
......@@ -476,30 +489,18 @@ paths:
security:
- oauth2:
- "read:libraries"
- "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:
......@@ -530,16 +532,18 @@ paths:
security:
- oauth2:
- "read:libraries"
- "read:libraries"
tags:
- "Library and metadata"
responses:
200:
description: ""
content:
application/json:
schema:
$ref: "./api/definitions.yml#/Album"
404:
description: "Not Found"
content:
application/json:
schema:
......@@ -555,16 +559,18 @@ paths:
security:
- oauth2:
- "read:libraries"
- "read:libraries"
tags:
- "Library and metadata"
responses:
200:
description: ""
content:
application/json:
schema:
$ref: "./api/definitions.yml#/LibraryPage"
404:
description: "Not Found"
content:
application/json:
schema:
......@@ -578,53 +584,42 @@ paths:
security:
- oauth2:
- "read:libraries"
- "read:libraries"
parameters:
- $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"