feat(docs): Split up schema file

docs/schema.yml

@@ -0,0 +1,927 @@
+openapi: "3.0.3"
+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: Collections
+  - name: History
+  - name: Instance
+  - name: Recordings
+  - name: Releases
+  - name: Tags
+paths:
+  /api/v2/collections:
+    get:
+      tags:
+        - Collections
+      summary: "Retrieve a list of collections from the server"
+      description: "Retrieve a list of collections stored on the server"
+      operationId: getCollections
+      parameters:
+        - $ref: "#/components/parameters/query"
+        - $ref: "#/components/parameters/pageParam"
+        - $ref: "#/components/parameters/pageSizeParam"
+      responses:
+        "200":
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/Pagination"
+                  - type: object
+                    required:
+                      - results
+                    properties:
+                      results:
+                        type: array
+                        items:
+                          $ref: "specs/collections/schema.yml#/Collection"
+    post:
+      tags:
+        - Collections
+      summary: "Add a new collection"
+      description: "Add a new collection to the server"
+      operationId: postCollection
+      responses:
+        "200":
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/Pagination"
+                  - type: object
+                    required:
+                      - results
+                    properties:
+                      results:
+                        type: array
+                        items:
+                          $ref: "specs/collections/schema.yml#/Collection"
+  /api/v2/collections/{guid}:
+    get:
+      tags:
+        - Collections
+      summary: "Retrieve a collection by GUID"
+      description: "Retrieve a collection by specifying its GUID"
+      operationId: getCollection
+      parameters:
+        - name: guid
+          in: path
+          required: true
+          description: The GUID of the collection
+          schema:
+            type: string
+            format: uuid
+      responses:
+        "200":
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: "specs/collections/schema.yml#/Collection"
+  /api/v2/instance/nodeinfo/2.1:
+    get:
+      tags:
+        - Instance
+      summary: "Retrieve nodeinfo data"
+      description: "Retrieve details about a Funkwhale server using the Nodeinfo standard"
+      operationId: getNodeinfo
+      responses:
+        "200":
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: "./specs/nodeinfo21/schema.yml#/Nodeinfo"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+  /api/v2/recordings:
+    get:
+      tags:
+        - Recordings
+      summary: "Retrieve a list of recordings"
+      description: "Retrieve a list of recordings uploaded to the server"
+      operationId: getRecordings
+      parameters:
+        - $ref: "#/components/parameters/query"
+        - $ref: "#/components/parameters/pageParam"
+        - $ref: "#/components/parameters/pageSizeParam"
+        - $ref: "specs/quality-filter/schema.yml#/FormatFilter"
+        - $ref: "specs/quality-filter/schema.yml#/TagsFilter"
+        - $ref: "specs/quality-filter/schema.yml#/MBIDFilter"
+        - $ref: "specs/quality-filter/schema.yml#/QualityFilter"
+        - name: release
+          in: query
+          required: false
+          description: Filter recordings by their associated release
+          schema:
+            type: string
+        - name: artist
+          in: query
+          required: false
+          description: Filter recordings by their associated artist
+          schema:
+            type: string
+        - name: id
+          in: query
+          required: false
+          description: Filter recordings by ID
+          schema:
+            type: array
+            items:
+              type: string
+        - name: collection
+          in: query
+          required: false
+          description: Filter recordings by collection ID
+          schema:
+            type: string
+            format: uuid
+        - name: mbid
+          in: query
+          required: false
+          description: Filter recordings by MusicBrainz ID
+          schema:
+            type: array
+            items:
+              type: string
+      responses:
+        "200":
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/Pagination"
+                  - type: object
+                    required:
+                      - results
+                    properties:
+                      results:
+                        type: array
+                        items:
+                          $ref: "#/components/schemas/Recording"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+  /api/v2/releases:
+    get:
+      tags:
+        - Releases
+      summary: Retrieve information about releases on the server
+      description: Retrieve a list of releases on the pod
+      operationId: getReleases
+      parameters:
+        - $ref: "#/components/parameters/query"
+        - $ref: "#/components/parameters/pageParam"
+        - $ref: "#/components/parameters/pageSizeParam"
+        - $ref: "specs/quality-filter/schema.yml#/FormatFilter"
+        - $ref: "specs/quality-filter/schema.yml#/TagsFilter"
+        - $ref: "specs/quality-filter/schema.yml#/MBIDFilter"
+        - $ref: "specs/quality-filter/schema.yml#/QualityFilter"
+        - name: artist
+          in: query
+          required: false
+          description: Filter releases by artist
+          schema:
+            type: integer
+        - name: id
+          in: query
+          required: false
+          description: Filter releases by ID
+          schema:
+            type: array
+            items:
+              type: string
+        - name: collection
+          in: query
+          required: false
+          description: Filter releases by collection ID
+          schema:
+            type: string
+            format: uuid
+        - name: mbid
+          in: query
+          required: false
+          description: Filter recordings by MusicBrainz ID
+          schema:
+            type: array
+            items:
+              type: string
+      responses:
+        "200":
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/Pagination"
+                  - type: object
+                    required:
+                      - results
+                    properties:
+                      results:
+                        type: array
+                        items:
+                          $ref: "#/components/schemas/Release"
+    post:
+      tags:
+        - Releases
+      summary: Add a new release to the server
+      description: Add a new release object to the server
+      operationId: postRelease
+      requestBody:
+        description: The release information you want to upload
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateRelease"
+      responses:
+        "202":
+          description: Created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SimpleRelease"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+  /api/v2/tags/podcasts:
+    get:
+      tags:
+        - Tags
+      summary: Retrieve podcast categories
+      description: Retrieve a list of podcast categories and the number of uploads tagged with those categories
+      operationId: getTagsPodcasts
+      parameters:
+        - $ref: "#/components/parameters/query"
+        - $ref: "#/components/parameters/pageParam"
+        - $ref: "#/components/parameters/pageSizeParam"
+        - name: ordering
+          in: query
+          required: false
+          description: |
+            The order in which results are presented. Preface with `-` to return items in descending order.
+          schema:
+            type: string
+            enum:
+              - "name"
+              - "creation_date"
+              - "tagged_items"
+              - "-name"
+              - "-creation_date"
+              - "-tagged_items"
+      responses:
+        "200":
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/Pagination"
+                  - type: object
+                    required:
+                      - results
+                    properties:
+                      results:
+                        type: array
+                        items:
+                          $ref: "#/components/schemas/Category"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+  /api/v2/tags/podcasts/{category}:
+    get:
+      tags:
+        - Tags
+      summary: Retrieve podcasts by category
+      description: Retrieve all podcasts in a category
+      operationId: getTagPodcasts
+      parameters:
+        - name: category
+          in: path
+          required: true
+          description: The category you want to return information about
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Category"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+  /api/v2/tags/music:
+    get:
+      tags:
+        - Tags
+      summary: Retrieve music genres
+      description: Retrieve a list of music genres and the number of uploads tagged with those categories
+      operationId: getTagsMusic
+      parameters:
+        - name: q
+          in: query
+          required: false
+          description: A free text field to filter genre names
+          schema:
+            type: string
+        - $ref: "#/components/parameters/pageParam"
+        - $ref: "#/components/parameters/pageSizeParam"
+        - name: ordering
+          in: query
+          required: false
+          description: |
+            The order in which results are presented. Preface with `-` to return items in descending order.
+          schema:
+            type: string
+            enum:
+              - "name"
+              - "creation_date"
+              - "tagged_items"
+              - "-name"
+              - "-creation_date"
+              - "-tagged_items"
+      responses:
+        "200":
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/Pagination"
+                  - type: object
+                    required:
+                      - results
+                    properties:
+                      results:
+                        type: array
+                        items:
+                          $ref: "#/components/schemas/Genre"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+  /api/v2/tags/music/{genre}:
+    get:
+      tags:
+        - Tags
+      summary: Retrieve music by genre
+      description: Retrieve all podcasts in a genre
+      operationId: getTagMusic
+      parameters:
+        - name: genre
+          in: path
+          required: true
+          description: The genre you want to return information about
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Genre"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+  /api/v2/history/listenings:
+    get:
+      tags:
+        - History
+      summary: Fetch a list of listenings
+      description: Fetch a list of listenings from public and followed users
+      operationId: getHistory
+      parameters:
+        - $ref: "#/components/parameters/pageParam"
+        - $ref: "#/components/parameters/pageSizeParam"
+      responses:
+        "200":
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/Pagination"
+                  - type: object
+                    required:
+                      - results
+                    properties:
+                      results:
+                        type: array
+                        items:
+                          $ref: "#/components/schemas/Listening"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+components:
+  responses:
+    Unauthorized:
+      description: Unauthorized
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+          examples:
+            code:
+              value: 401
+            message:
+              value: User not authorized
+  parameters:
+    pageParam:
+      name: page
+      in: query
+      required: false
+      description: The number of the result page you want to return
+      schema:
+        type: number
+    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:
+    Actor:
+      allOf:
+        - $ref: "#/components/schemas/SimpleActor"
+        - type: object
+          properties:
+            lastFetchDate:
+              type: string
+              format: date-time
+            manuallyApprovesFollowers:
+              type: boolean
+            type:
+              type: string
+              enum:
+                - person
+                - tombstone
+                - application
+                - group
+                - organization
+                - service
+    Artist:
+      allOf:
+        - $ref: "specs/multi-artist/schema.yml#/SimpleArtist"
+        - type: object
+          properties:
+            creationDate:
+              type: string
+              format: date-time
+            recordingCount:
+              type: integer
+            tags:
+              type: array
+              items:
+                type: string
+            releases:
+              type: array
+              items:
+                $ref: "#/components/schemas/SimpleRelease"
+    ArtistCredit:
+      type: object
+      required:
+        - name
+        - id
+      properties:
+        name:
+          type: string
+        id:
+          type: integer
+        joinPhrase:
+          type: string
+    Category:
+      type: object
+      required:
+        - name
+        - createdDate
+        - resultsPage
+      properties:
+        name:
+          type: string
+        createdDate:
+          type: string
+          format: date-time
+        taggedItems:
+          type: number
+        resultsPage:
+          type: string
+          format: url
+    CoverUrls:
+      type: object
+      required:
+        - uuid
+        - mimetype
+        - size
+        - creationDate
+        - urls
+      properties:
+        uuid:
+          type: string
+          format: uuid
+        mimetype:
+          type: string
+        size:
+          type: integer
+        creationDate:
+          type: string
+          format: date-time
+        urls:
+          type: object
+          required:
+            - original
+          properties:
+            source:
+              type: string
+              format: url
+            original:
+              type: string
+              format: url
+    CreateRelease:
+      type: object
+      required:
+        - title
+        - artist
+      properties:
+        title:
+          type: string
+        releaseDate:
+          type: string
+          format: date-time
+        tags:
+          type: array
+          items:
+            type: string
+        type:
+          $ref: "#/components/schemas/ReleaseTypeEnum"
+        description:
+          type: object
+          required:
+            - text
+            - contentType
+          properties:
+            text:
+              type: string
+              description: A description of the release
+            contentType:
+              type: string
+              enum:
+                - "text/html"
+                - "text/markdown"
+                - "text/plain"
+            html:
+              type: string
+        artist:
+          type: string
+          description: The name of the associated artist
+    Error:
+      type: object
+      properties:
+        code:
+          type: string
+        message:
+          type: string
+      required:
+        - code
+        - message
+    Genre:
+      type: object
+      properties:
+        genre:
+          type: string
+        created_date:
+          type: string
+          format: date-time
+        tagged_items:
+          type: number
+        results_page:
+          type: string
+          format: url
+    Listening:
+      type: object
+      required:
+        - guid
+        - createdDate
+        - user
+        - recording
+      properties:
+        guid:
+          type: string
+          format: uuid
+        createdDate:
+          type: string
+          format: date-time
+        recording:
+          $ref: "#/components/schemas/SimpleRecording"
+        user:
+          $ref: "#/components/schemas/SimpleUser"
+    Pagination:
+      type: object
+      required:
+        - total
+      properties:
+        total:
+          type: integer
+        next:
+          type: string
+          format: url
+        previous:
+          type: string
+          format: url
+    Recording:
+      allOf:
+        - $ref: "#/components/schemas/SimpleRecording"
+        - type: object
+          required:
+            - creationDate
+            - downloadsCount
+            - attributedTo
+          properties:
+            creationDate:
+              type: string
+              format: date-time
+            copyright:
+              format: string
+            license:
+              format: string
+            tags:
+              format: array
+              items:
+                type: string
+            mbid:
+              type: string
+              format: uuid
+            downloadsCount:
+              type: integer
+            discNumber:
+              type: integer
+            position:
+              type: integer
+            attributedTo:
+              $ref: "#/components/schemas/SimpleActor"
+            collections:
+              type: array
+              items:
+                $ref: "specs/collections/schema.yml#/SimpleCollection"
+    Release:
+      allOf:
+        - $ref: "#/components/schemas/SimpleRelease"
+        - type: object
+          properties:
+            creationDate:
+              type: string
+              format: date-time
+            releaseDate:
+              type: string
+              format: date
+            recordingCount:
+              type: integer
+            duration:
+              type: integer
+            attributedTo:
+              $ref: "#/components/schemas/SimpleActor"
+            local:
+              type: boolean
+            recordings:
+              type: array
+              items:
+                $ref: "#/components/schemas/SimpleRecording"
+    ReleaseGroup:
+      type: object
+      required:
+        - guid
+        - artist
+        - primaryType
+      properties:
+        guid:
+          type: string
+          format: uuid
+        artistCredit:
+          type: array
+          items:
+            $ref: "specs/multi-artist/schema.yml#/ArtistCredit"
+        primaryType:
+          $ref: "#/components/schemas/ReleaseTypeEnum"
+        secondaryType:
+          type: string
+          enum:
+            - compilation
+            - soundtrack
+            - spokenword
+            - interview
+            - audiobook
+            - audio-drama
+            - live
+            - remix
+            - dj-mix
+            - mixtape
+            - demo
+            - field-recording
+        releases:
+          type: array
+          items:
+            $ref: "#/components/schemas/SimpleRelease"
+    ReleaseTypeEnum:
+      type: string
+      default: album
+      description: The type of release
+      enum:
+        - album
+        - single
+        - ep
+        - broadcast
+        - other
+    SimpleActor:
+      type: object
+      required:
+        - fid
+        - preferredUsername
+        - fullUsername
+        - local
+        - domain
+      properties:
+        fid:
+          type: string
+          format: url
+        url:
+          type: string
+          format: url
+        fullUsername:
+          type: string
+        preferredUsername:
+          type: string
+        name:
+          type: string
+        domain:
+          type: string
+        local:
+          type: boolean
+    SimpleArtist:
+      type: object
+      required:
+        - id
+        - fid
+        - name
+        - contentCategory
+        - local
+      properties:
+        id:
+          type: integer
+        fid:
+          type: string
+          format: url
+        mbid:
+          type: string
+          format: uuid
+        name:
+          type: string
+        contentCategory:
+          type: string
+          enum:
+            - music
+            - podcast
+            - other
+        local:
+          type: boolean
+        channel:
+          type: string
+          format: uuid
+    SimpleRecording:
+      type: object
+      required:
+        - id
+        - fid
+        - name
+        - playable
+        - local
+        - release
+        - artist
+        - cover
+      properties:
+        id:
+          type: integer
+        fid:
+          type: string
+          format: url
+        name:
+          type: string
+        playable:
+          type: boolean
+        local:
+          type: boolean
+        release:
+          $ref: "#/components/schemas/SimpleRelease"
+        artistCredit:
+          type: array
+          items:
+            $ref: "specs/multi-artist/schema.yml#/ArtistCredit"
+        cover:
+          $ref: "#/components/schemas/CoverUrls"
+    SimpleRelease:
+      type: object
+      required:
+        - id
+        - fid
+        - name
+        - local
+      properties:
+        id:
+          type: integer
+        fid:
+          type: string
+          format: url
+        mbid:
+          type: string
+          format: uuid
+        name:
+          type: string
+        playable:
+          type: boolean
+        releaseGroup:
+          type: string
+          format: uuid
+        cover:
+          $ref: "#/components/schemas/CoverUrls"
+    SimpleUser:
+      type: object
+      required:
+        - id
+        - username
+        - fullUsername
+        - avatar
+      properties:
+        id:
+          type: integer
+        username:
+          type: string
+        fullUsername:
+          type: string
+        preferredUsername:
+          type: string
+        avatar:
+          $ref: "#/components/schemas/CoverUrls"
+  securitySchemes:
+    oauth2:
+      type: oauth2
+      description: This API uses OAuth 2 with the Authorization Code flow. You can register an app using the /oauth/apps/ endpoint.
+      flows:
+        authorizationCode:
+          authorizationUrl: /authorize
+          tokenUrl: /api/v1/oauth/token/
+          refreshUrl: /api/v1/oauth/token/
+          scopes:
+            "read": "Read-only access to all user data"
+            "write": "Write-only access on all user data"
+            "read:edits": "Read-only access to edits"
+            "write:edits": "Write-only access to edits"
+            "read:favorites": "Read-only access to favorites"
+            "write:favorites": "Write-only access to favorites"
+            "read:filters": "Read-only to to content filters"
+            "write:filters": "Write-only access to content-filters"
+            "read:follows": "Read-only to follows"
+            "write:follows": "Write-only access to follows"
+            "read:libraries": "Read-only access to library and uploads"
+            "write:libraries": "Write-only access to libraries"
+            "read:listenings": "Read-only access to listening history"
+            "write:listenings": "Write-only access to listening history"
+            "read:notifications": "Read-only access to notifications"
+            "write:notifications": "Write-only access to notifications"
+            "read:playlists": "Read-only access to playlists"
+            "write:playlists": "Write-only access to playlists"
+            "read:profile": "Read-only access to profile data"
+            "write:profile": "Write-only access to profile data"
+            "read:radios": "Read-only access to radios"
+            "write:radios": "Write-only access to radios"
+            "read:reports": "Read-only access to reports"
+            "write:reports": "Write-only access to reports"
+            "read:security": "Read-only access security settings"
+            "write:security": "write-only access security settings"
+
+security:
+  - oauth2: []

docs/specs/collections/schema.yml

@@ -0,0 +1,24 @@
+SimpleCollection:
+  type: object
+  required:
+    - guid
+    - name
+    - local
+    - owner
+  properties:
+    guid:
+      type: string
+      format: uuid
+    name:
+      type: string
+    local:
+      type: boolean
+    owner:
+      $ref: "../../schema.yml#/components/schemas/SimpleActor"
+Collection:
+  allOf:
+    - $ref: "#/SimpleCollection"
+    - type: object
+      properties:
+        items:
+          type: integer

docs/specs/multi-artist/schema.yml

@@ -0,0 +1,60 @@
+SimpleArtist:
+  type: object
+  required:
+    - id
+    - fid
+    - name
+    - contentCategory
+    - local
+  properties:
+    id:
+      type: integer
+    fid:
+      type: string
+      format: url
+    mbid:
+      type: string
+      format: uuid
+    name:
+      type: string
+    contentCategory:
+      type: string
+      enum:
+        - music
+        - podcast
+        - other
+    local:
+      type: boolean
+    channel:
+      type: string
+      format: uuid
+Artist:
+  allOf:
+    - $ref: "#/SimpleArtist"
+    - type: object
+      properties:
+        creationDate:
+          type: string
+          format: date-time
+        recordingCount:
+          type: integer
+        tags:
+          type: array
+          items:
+            type: string
+        releases:
+          type: array
+          items:
+            $ref: "../../schema.yml#/components/schemas/SimpleRelease"
+ArtistCredit:
+  type: object
+  required:
+    - name
+    - id
+  properties:
+    name:
+      type: string
+    id:
+      type: integer
+    joinPhrase:
+      type: string

docs/specs/quality-filter/schema.yml

@@ -0,0 +1,44 @@
+FormatFilter:
+  name: format
+  in: query
+  required: false
+  description: "Comma separated list of file extensions to filter results by"
+  schema:
+    type: array
+    items:
+      type: string
+      enum:
+        - "flac"
+        - "ogg"
+        - "mp3"
+        - "opus"
+        - "aac"
+        - "m4a"
+        - "aiff"
+        - "aif"
+TagsFilter:
+  name: has_tags
+  in: query
+  required: false
+  description: "Filter content by whether it has tags (true) or not (false). Leave this blank to return all results"
+  schema:
+    type: boolean
+MBIDFilter:
+  name: has_mbid
+  in: query
+  required: false
+  description: "Filter content by whether it has a MusicBrainz ID (true) or not (false). Leave this blank to return all results"
+  schema:
+    type: boolean
+QualityFilter:
+  name: quality
+  in: query
+  required: false
+  description: "Filter content based on the quality of the associated files"
+  schema:
+    type: string
+    enum:
+      - "low"
+      - "medium"
+      - "high"
+      - "very_high"