feat(docs): Add some initial structure to schema

docs/specs/nodeinfo21/schema.yml

@@ -1,4 +1,4 @@
-openapi: "3.0.3"
+openapi: "3.1.0"
 info:
   description: "Interactive documentation for [Funkwhale](https://funkwhale.audio) API."
   version: "2.0.0"
@@ -21,11 +21,40 @@ servers:
           - "https"
         default: "https"
 tags:
+  - name: Collections
+  - name: History
   - name: Instance
-    description: Information about the server
+  - name: Recordings
-  - name: Content
+  - name: Releases
-    description: Information about content on the server
+  - 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: getCollection
+      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: "#/components/schemas/Collection"
   /api/v2/instance/nodeinfo/2.1:
     get:
       tags:
@@ -40,37 +69,161 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Nodeinfo"
-            application/xml:
+        "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"
+        - 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:
-                $ref: "#/components/schemas/Nodeinfo"
+                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"
+        - 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:
+        "200":
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SimpleRelease"
         "401":
           $ref: "#/components/responses/Unauthorized"
   /api/v2/tags/podcasts:
     get:
       tags:
-        - Content
+        - Tags
       summary: Retrieve podcast categories
       description: Retrieve a list of podcast categories and the number of uploads tagged with those categories
       operationId: getTagsPodcasts
       parameters:
-        - name: q
+        - $ref: "#/components/parameters/query"
-          in: query
+        - $ref: "#/components/parameters/pageParam"
-          required: false
+        - $ref: "#/components/parameters/pageSizeParam"
-          description: A free text field to filter category names
-          schema:
-            type: string
-        - name: page
-          in: query
-          required: false
-          description: The number of the result page you want to return
-          schema:
-            type: number
-        - name: page_size
-          in: query
-          required: false
-          description: The number of results to return on each page. Defaults to 50.
-          schema:
-            type: number
         - name: ordering
           in: query
           required: false
@@ -91,18 +244,24 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/Categories"
+                allOf:
-            application/xml:
+                  - $ref: "#/components/schemas/Pagination"
-              schema:
+                  - type: object
-                $ref: "#/components/schemas/Categories"
+                    required:
+                      - results
+                    properties:
+                      results:
+                        type: array
+                        items:
+                          $ref: "#/components/schemas/Category"
         "401":
           $ref: "#/components/responses/Unauthorized"
   /api/v2/tags/podcasts/{category}:
     get:
       tags:
-        - Content
+        - Tags
-      summary: Retrieve podcast categories
+      summary: Retrieve podcasts by category
-      description: Retrieve a list of podcast categories and the number of uploads tagged with those categories
+      description: Retrieve all podcasts in a category
       operationId: getTagPodcasts
       parameters:
         - name: category
@@ -118,15 +277,12 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Category"
-            application/xml:
-              schema:
-                $ref: "#/components/schemas/Category"
         "401":
           $ref: "#/components/responses/Unauthorized"
   /api/v2/tags/music:
     get:
       tags:
-        - Content
+        - Tags
       summary: Retrieve music genres
       description: Retrieve a list of music genres and the number of uploads tagged with those categories
       operationId: getTagsMusic
@@ -137,18 +293,8 @@ paths:
           description: A free text field to filter genre names
           schema:
             type: string
-        - name: page
+        - $ref: "#/components/parameters/pageParam"
-          in: query
+        - $ref: "#/components/parameters/pageSizeParam"
-          required: false
-          description: The number of the result page you want to return
-          schema:
-            type: number
-        - name: page_size
-          in: query
-          required: false
-          description: The number of results to return on each page. Defaults to 50.
-          schema:
-            type: number
         - name: ordering
           in: query
           required: false
@@ -169,18 +315,24 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/Genres"
+                allOf:
-            application/xml:
+                  - $ref: "#/components/schemas/Pagination"
-              schema:
+                  - type: object
-                $ref: "#/components/schemas/Genres"
+                    required:
+                      - results
+                    properties:
+                      results:
+                        type: array
+                        items:
+                          $ref: "#/components/schemas/Genre"
         "401":
           $ref: "#/components/responses/Unauthorized"
   /api/v2/tags/music/{genre}:
     get:
       tags:
-        - Content
+        - Tags
-      summary: Retrieve podcast categories
+      summary: Retrieve music by genre
-      description: Retrieve a list of podcast categories and the number of uploads tagged with those categories
+      description: Retrieve all podcasts in a genre
       operationId: getTagMusic
       parameters:
         - name: genre
@@ -196,9 +348,34 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Genre"
-            application/xml:
+        "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:
-                $ref: "#/components/schemas/Genre"
+                allOf:
+                  - $ref: "#/components/schemas/Pagination"
+                  - type: object
+                    required:
+                      - results
+                    properties:
+                      results:
+                        type: array
+                        items:
+                          $ref: "#/components/schemas/Listening"
         "401":
           $ref: "#/components/responses/Unauthorized"
 components:
@@ -209,44 +386,72 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/Error"
-          example:
+          examples:
-            code: 401
+            code:
-            message: User not authorized
+              value: 401
-        application/xml:
+            message:
-          schema:
+              value: User not authorized
-            $ref: "#/components/schemas/Error"
+  parameters:
-          example:
+    pageParam:
-            code: 401
+      name: page
-            message: User not authorized
+      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:
-    Categories:
+    Actor:
-      type: object
+      allOf:
-      properties:
+        - $ref: "#/components/schemas/SimpleActor"
-        total:
+        - type: object
-          type: number
+          properties:
-        next:
+            lastFetchDate:
-          type: string
+              type: string
-          format: url
+              format: date-time
-        previous:
+            manuallyApprovesFollowers:
-          type: string
+              type: boolean
-          format: url
+            type:
-        results:
+              type: string
-          type: array
+              enum:
-          items:
+                - person
-            $ref: "#/components/schemas/Category"
+                - tombstone
-      example:
+                - application
-        total: 5
+                - group
-        next: https://demo.funkwhale.audio/api/v2/categories?page=2&page_size=2&q=crime
+                - organization
-        previous: null
+                - service
-        results:
+    Artist:
-          - category: "True Crime"
+      allOf:
-            created_date: "2020-01-01T00:00:00.000Z"
+        - $ref: "#/components/schemas/SimpleArtist"
-            tagged_items: 5
+        - type: object
-            results_page: "https://demo.funkwhale.audio/library/categories/True%20Crime"
+          properties:
-          - category: "True Stories"
+            creationDate:
-            created_date: "2023-12-15T23:32:52.000Z"
+              type: string
-            tagged_items: 200
+              format: date-time
-            results_page: "https://demo.funkwhale.audio/library/categories/True%20Stories"
+            recordingCount:
+              type: integer
+            tags:
+              type: array
+              items:
+                type: string
+            releases:
+              type: array
+              items:
+                $ref: "#/components/schemas/SimpleRelease"
     Category:
       type: object
       properties:
@@ -260,39 +465,90 @@ components:
         results_page:
           type: string
           format: url
-      example:
+    Collection:
-        category: "True Crime"
+      allOf:
-        created_date: "2020-01-01T00:00:00.000Z"
+        - $ref: "#/components/schemas/SimpleCollection"
-        tagged_items: 5
+        - type: object
-        results_page: "https://demo.funkwhale.audio/library/categories/True%20Crime"
+          properties:
-    Genres:
+            items:
+              type: integer
+    CoverUrls:
       type: object
+      required:
+        - uuid
+        - mimetype
+        - size
+        - creationDate
+        - urls
       properties:
-        total:
+        uuid:
-          type: number
-        next:
           type: string
-          format: url
+          format: uuid
-        previous:
+        mimetype:
           type: string
-          format: url
+        size:
-        results:
+          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:
-            $ref: "#/components/schemas/Genre"
+            type: string
-      example:
+        type:
-        total: 5
+          $ref: "#/components/schemas/ReleaseTypeEnum"
-        next: https://demo.funkwhale.audio/api/v2/categories?page=2&page_size=2&q=rock
+        description:
-        previous: null
+          type: object
-        results:
+          required:
-          - genre: "Acoustic Rock"
+            - text
-            created_date: "2020-01-01T00:00:00.000Z"
+            - contentType
-            tagged_items: 5
+          properties:
-            results_page: "https://demo.funkwhale.audio/library/categories/Acoustic%20Rock"
+            text:
-          - genre: "Surf Rock"
+              type: string
-            created_date: "2023-12-15T23:32:52.000Z"
+              description: A description of the release
-            tagged_items: 200
+            contentType:
-            results_page: "https://demo.funkwhale.audio/library/categories/Surf%20Rock"
+              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:
@@ -306,11 +562,24 @@ components:
         results_page:
           type: string
           format: url
-      example:
+    Listening:
-        genre: "Acoustic Rock"
+      type: object
-        created_date: "2020-01-01T00:00:00.000Z"
+      required:
-        tagged_items: 5
+        - guid
-        results_page: "https://demo.funkwhale.audio/library/categories/Acoustic%20Rock"
+        - 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"
     Nodeinfo:
       type: object
       required:
@@ -338,7 +607,8 @@ components:
                 - "Funkwhale"
             version:
               type: string
-              example: "1.4.0"
+              examples:
+                - "1.4.0"
             repository:
               type: string
               format: url
@@ -365,7 +635,7 @@ components:
               - "tent"
               - "xmpp"
               - "zot"
-          example:
+          examples:
             - "activitypub"
         services:
           type: object
@@ -505,11 +775,11 @@ components:
                       type: number
                     hoursOfContent:
                       type: number
-                  example:
+                  examples:
-                    artists: 1000
+                    - artists: 1000
-                    releases: 10000
+                      releases: 10000
-                    recordings: 150000
+                      recordings: 150000
-                    hoursOfContent: 7500
+                      hoursOfContent: 7500
                 topMusicCategories:
                   type: array
                   items:
@@ -570,23 +840,271 @@ components:
               type: array
               items:
                 type: string
-              example:
+              examples:
                 - "channels"
                 - "podcasts"
                 - "collections"
                 - "audiobooks"
                 - "federation"
                 - "anonymousCanListen"
-    Error:
+    Pagination:
       type: object
-      properties:
-        code:
-          type: string
-        message:
-          type: string
       required:
-        - code
+        - total
-        - message
+      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: "#/components/schemas/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
+        artist:
+          $ref: "#/components/schemas/SimpleArtist"
+        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
+    SimpleCollection:
+      type: object
+      required:
+        - uuid
+        - name
+        - local
+        - owner
+      properties:
+        uuid:
+          type: string
+          format: uuid
+        name:
+          type: string
+        local:
+          type: boolean
+        owner:
+          $ref: "#/components/schemas/SimpleActor"
+    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"
+        artist:
+          $ref: "#/components/schemas/SimpleArtist"
+        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
@@ -602,7 +1120,7 @@ components:
             "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 favorits"
+            "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"