API docs

dev.yml

@@ -161,6 +161,7 @@ services:
       - "8002:8080"
     volumes:
       - "./docs/swagger.yml:/usr/share/nginx/html/swagger.yml"
+      - "./docs/api:/usr/share/nginx/html/api"
 
   # minio:
   #   image: minio/minio

docs/api/parameters.yml

+ChannelOrdering:
+  - $ref: "#/parameters/Ordering"
+  - default: "-creation_date"
+    schema:
+      required: false
+      type: "string"
+      example: "-creation_date"
+      enum:
+        - creation_date
+        - artist__modification_date
+
+External:
+  name: "external"
+  in: "query"
+  default: null
+  description: "Filter/exclude channels created from a third-party, non-Funkwhale RSS feed"
+  schema:
+    required: false
+    type: "boolean"
+
+
+ObjectId:
+  name: id
+  in: path
+  description: Object ID
+  required: true
+  schema:
+    type: integer
+    format: int64
+Ordering:
+  name: "ordering"
+  in: "query"
+  description: "Ordering for the results, prefix with - for DESC ordering"
+
+PageNumber:
+  in: query
+  name: page
+  schema:
+    type: "integer"
+    format: "int64"
+    example: 1
+    default: 1
+    minimum: 1
+PageSize:
+  in: query
+  name: page_size
+  schema:
+    type: "integer"
+    format: "int64"
+    example: 16
+    default: 25
+    minimum: 1
+    maximum: 25
+Playable:
+  name: "playable"
+  in: "query"
+  default: null
+  description: "Filter/exclude resources with playable tracks"
+  schema:
+    required: false
+    type: "boolean"
+Refresh:
+  name: "refresh"
+  in: "query"
+  default: false
+  description: "Trigger an ActivityPub fetch to refresh local data"
+  schema:
+    required: false
+    type: "boolean"
+
+Scope:
+  name: "scope"
+  in: "query"
+  default: "all"
+  description: |
+    Limit the results to a given user or pod:
+      - Use `all` (or do not specify the property to disable scope filtering)
+      - Use `me` to retrieve content relative to the current user
+      - Use `actor:alice@example.com` to retrieve content relative to the account `alice@example.com
+      - Use `domain:example.com` to retrieve content relative to the domain `example.com
+  schema:
+    required: false
+    type: "string"
+    enum:
+    - "me"
+    - "all"
+    - "actor:alice@example.com"
+    - "domain:example.com"
+
+Search:
+  name: "q"
+  in: "query"
+  default: "all"
+  description: "Limit the results to the corresponding search query"
+  schema:
+    required: false
+    type: "string"
+    example: "Bonobo"
+
+Subscribed:
+  name: "subscribed"
+  in: "query"
+  description: "Limit or exclude results with a matching subsription from the current user"
+  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"
+  schema:
+    required: false
+    type: array
+    collectionFormat: csv
+    example:
+      - rock
+      - metal

docs/api/properties.yml

+
+description:
+  type: object
+  description: Text content associated with another resource, like and artist or channel.
+  properties:
+    text:
+      type: string
+      example: "This is **me**"
+      description: "The raw user input"
+    content_type:
+      type: string
+      enum:
+        - text/markdown
+        - text/plain
+        - text/html
+      description: "The raw user input"
+    html:
+      type: string
+      description: "HTML output based on user input"
+      readOnly: true
+
+mbid:
+  type: "string"
+  format: "uuid"
+  description: "A musicbrainz ID"
+creation_date:
+  type: "string"
+  format: "date-time"
+  description: "Creation date of the resource"
+
+modification_date:
+  type: "string"
+  format: "date-time"
+  description: "Last modification date of th resource"
+privacy_level:
+  type: string
+  example: "me"
+  description: |
+    * `me`: private
+    * `instance`: accessible by local users
+    * `everyone`: public (including over federation)
+  enum:
+    - "me"
+    - "instance"
+    - "everyone"
+fid:
+  type: "string"
+  format: "uri"
+  description: "Federation ID"
+  example: "https://my.instance/federation/music/libraries/3fa85f64-5717-4562-b3fc-2c963f66afa6"
+audio_mimetype:
+  type: string
+  example: "audio/ogg"
+  enum:
+    - "audio/ogg"
+    - "audio/mpeg"
+    - "audio/x-flac"
+    - "audio/flac"
+image_mimetype:
+  type: string
+  example: "image/png"
+  enum:
+    - "image/png"
+    - "image/jpeg"
+import_status:
+  type: string
+  example: "finished"
+  enum:
+    - "draft"
+    - "pending"
+    - "finished"
+    - "errored"
+    - "skipped"
+  description: |
+    * `draft`: waiting for further modifications from the owner
+    * `pending`: waiting to be processed by the server
+    * `finished`: successfully processed by the server
+    * `errored`: couldn't be processed by the server (e.g because of a tagging issue)
+    * `skipped`: processed by the server but skipped, because considered as a duplicate of an existing upload
+
+transcode_options:
+  type: string
+  enum:
+    - "ogg"
+    - "mp3"
+
+tags:
+  type: array
+  description: A list of hashtags associated with a resource
+  items:
+    type: string
+    example: "Rock"
+
+content_category:
+  type: "string"
+  description: Used to what kind of content is published in a chanel
+  enum:
+    - music
+    - podcast
+    - other

docs/build_swagger.sh

@@ -6,4 +6,5 @@ rm -rf $TARGET_PATH /tmp/swagger-ui
 git clone --branch="v$SWAGGER_VERSION" --depth=1 "https://github.com/swagger-api/swagger-ui.git" /tmp/swagger-ui
 mv /tmp/swagger-ui/dist $TARGET_PATH
 cp swagger.yml $TARGET_PATH
+cp -r api $TARGET_PATH/api
 sed -i "s,http://petstore.swagger.io/v2/swagger.json,swagger.yml,g" $TARGET_PATH/index.html