substantial cleaning and sorting

.github/workflows/build-and-copy-spec.yml

@@ -21,18 +21,37 @@ jobs:
       - name: Install swagger-cli
         run: |
           npm install -g swagger-cli
-      - name: Dereference Plex API Specification
+
+      - name: Dereference Plex Media Server Specification
         run: |
-          swagger-cli bundle --dereference referenced/plex-api-spec.yaml -t yaml -o plex-api-spec-dereferenced.yaml
+          swagger-cli bundle --dereference pms/pms-spec.yaml -t yaml -o plex-media-server-spec-dereferenced.yaml
+
+      - name: Dereference Plex TV Specification
+        run: |
+          swagger-cli bundle --dereference plextv/plextv-spec.yaml -t yaml -o plex-tv-spec-dereferenced.yaml
+
       - name: Pushes Dereferenced Specification File
         uses: dmnemec/copy_file_to_another_repo_action@main
         env:
           API_TOKEN_GITHUB: ${{ secrets.API_TOKEN_GITHUB }}
         with:
-          source_file: plex-api-spec-dereferenced.yaml
+          source_file: plex-media-server-spec-dereferenced.yaml
           destination_repo: lukehagar/plex-docs
           destination_folder: static
           user_email: lukeslakemail@gmail.com
           user_name: lukehagar
-          commit_message: Updating OpenAPI Spec
+          commit_message: Updating PMS Spec
+
+      - name: Pushes Dereferenced Specification File
+        uses: dmnemec/copy_file_to_another_repo_action@main
+        env:
+          API_TOKEN_GITHUB: ${{ secrets.API_TOKEN_GITHUB }}
+        with:
+          source_file: plex-tv-spec-dereferenced.yaml
+          destination_repo: lukehagar/plex-docs
+          destination_folder: static
+          user_email: lukeslakemail@gmail.com
+          user_name: lukehagar
+          commit_message: Updating PlexTV Spec
+
       - uses: stefanzweifel/git-auto-commit-action@v4

.github/workflows/build-typescript-sdk.yml

@@ -36,8 +36,15 @@ jobs:
         id: buildTS
         run: |
           cd sdk-ts
-          rm -rf plexjs/
+          rm -rf plexjs/pms
-          java -jar openapi-generator-cli.jar generate -i ../referenced/plex-api-spec.yaml -g typescript-axios -o plexjs/ --global-property skipFormModel=false --config config.yaml
+          java -jar openapi-generator-cli.jar generate -i ../pms/pms-spec.yaml -g typescript-axios -o plexjs/pms --global-property skipFormModel=false --config sdk-resources/pms-config.yaml
+
+      - name: Build TS SDK
+        id: buildTS
+        run: |
+          cd sdk-ts
+          rm -rf plexjs/plextv
+          java -jar openapi-generator-cli.jar generate -i ../plextv/plextv-spec.yaml -g typescript-axios -o plexjs/plextv --global-property skipFormModel=false --config sdk-resources/plextv-config.yaml
 
       - name: Run npm install and build Typescript SDK
         id: buildSDK

package.json

@@ -1,5 +0,0 @@
-{
-  "scripts": {
-    "build": "swagger-cli bundle --dereference referenced/plex-api-spec.yaml -t yaml -o plex-api-spec-dereferenced.yaml"
-  }
-}

plextv/plextv-spec.yaml

@@ -0,0 +1,147 @@
+openapi: 3.1.0
+info:
+  title: Plex-API
+  summary: A Plex.TV API Map
+  description: An Open API Spec for interacting with Plex.tv
+  version: 0.0.3
+  contact:
+    name: Luke Hagar
+    url: "https://www.LukeHagar.com"
+    email: Lukeslakemail@gmail.com
+  license:
+    name: MIT
+    identifier: MIT
+    url: https://opensource.org/licenses/MIT
+
+servers:
+  - url: https://plex.tv/api/v2
+
+security:
+  - Token: []
+    ClientIdentifier: []
+    Device: []
+    DeviceName: []
+    Platform: []
+    PlatformVersion: []
+    Product: []
+    Version: []
+
+components:
+  securitySchemes:
+    Token: # arbitrary name for the security scheme
+      description: Plex Authentication Token
+      type: apiKey
+      in: header # can be "header", "query" or "cookie"
+      name: X-Plex-Token # name of the header, query parameter or cookie
+    ClientIdentifier: # arbitrary name for the security scheme
+      description: Plex Authentication Token
+      type: apiKey
+      in: header # can be "header", "query" or "cookie"
+      name: X-Plex-Client-Identifier # name of the header, query parameter or cookie
+    DeviceName: # arbitrary name for the security scheme
+      description: Primary name for the device eg. `Plex Web (Chrome)`
+      type: apiKey
+      in: header # can be "header", "query" or "cookie"
+      name: X-Plex-Device-Name # name of the header, query parameter or cookie
+    Device: # arbitrary name for the security scheme
+      description: |
+        The type of device your application is running on
+        Device name and or model number, eg `iPhone3,2`, `Motorola XOOM™`, `LG5200TV`
+      type: apiKey
+      in: header # can be "header", "query" or "cookie"
+      name: X-Plex-Device # name of the header, query parameter or cookie
+    PlatformVersion: # arbitrary name for the security scheme
+      description: |
+        Operating system version
+        eg `4.3.1`, `10.6.7`, `3.2`
+      type: apiKey
+      in: header # can be "header", "query" or "cookie"
+      name: X-Plex-Platform-Version # name of the header, query parameter or cookie
+    Platform: # arbitrary name for the security scheme
+      description: |
+        Platform name 
+        eg: `Web`, `iOS`, `MacOSX`, `Android`, `LG`
+      type: apiKey
+      in: header # can be "header", "query" or "cookie"
+      name: X-Plex-Platform # name of the header, query parameter or cookie
+    Product: # arbitrary name for the security scheme
+      description: |
+        Plex application name 
+        eg: `Laika`, `Plex Media Server`, `Media Link`
+      type: apiKey
+      in: header # can be "header", "query" or "cookie"
+      name: X-Plex-Product # name of the header, query parameter or cookie
+    Version: # arbitrary name for the security scheme
+      description: Plex application version number
+      type: apiKey
+      in: header # can be "header", "query" or "cookie"
+      name: X-Plex-Version # name of the header, query parameter or cookie
+
+paths:
+  # Plex.tv API endpoints
+  /companions:
+    $ref: "./paths/companions.yaml"
+  /geoip:
+    $ref: "./paths/geoip.yaml"
+  /home:
+    $ref: "./paths/home.yaml"
+  /pins:
+    $ref: "./paths/pins.yaml"
+  /pins/{pinID}:
+    $ref: "./paths/pins-id.yaml"
+  /resources:
+    $ref: "./paths/resources.yaml"
+  /user:
+    $ref: "./paths/user.yaml"
+  /user/settings:
+    $ref: "./paths/user-settings.yaml"
+  /user/settings/opt_outs:
+    $ref: "./paths/user-settings-opt_outs.yaml"
+
+tags:
+  - name: Activities
+    description: |
+      Activities are awesome. They provide a way to monitor and control asynchronous operations on the server. In order to receive real-time updates for activities, a client would normally subscribe via either EventSource or Websocket endpoints.
+      Activities are associated with HTTP replies via a special `X-Plex-Activity` header which contains the UUID of the activity.
+      Activities are optional cancellable. If cancellable, they may be cancelled via the `DELETE` endpoint. Other details:
+      - They can contain a `progress` (from 0 to 100) marking the percent completion of the activity.
+      - They must contain an `type` which is used by clients to distinguish the specific activity.
+      - They may contain a `Context` object with attributes which associate the activity with various specific entities (items, libraries, etc.)
+      - The may contain a `Response` object which attributes which represent the result of the asynchronous operation.
+  - name: Authentication
+    description: |
+      API Calls regarding authentication for Plex Media Server
+  - name: Butler
+    description: |
+      Butler is the task manager of the Plex Media Server Ecosystem.
+  - name: Server
+    description: |
+      Operations against the Plex Media Server System.
+  - name: Updater
+    description: |
+      This describes the API for searching and applying updates to the Plex Media Server.
+      Updates to the status can be observed via the Event API.
+  - name: Log
+    description: |
+      Submit logs to the Log Handler for Plex Media Server
+  - name: Security
+    description: |
+      API Calls against Security for Plex Media Server
+  - name: Library
+    description: |
+      API Calls interacting with Plex Media Server Libraries
+  - name: Hubs
+    description: |
+      Hubs are a structured two-dimensional container for media, generally represented by multiple horizontal rows.
+  - name: Playlists
+    description: |
+      Playlists are ordered collections of media. They can be dumb (just a list of media) or smart (based on a media query, such as "all albums from 2017"). 
+      They can be organized in (optionally nesting) folders.
+      Retrieving a playlist, or its items, will trigger a refresh of its metadata. 
+      This may cause the duration and number of items to change.
+  - name: Search
+    description: |
+      API Calls that perform search operations with Plex Media Server
+  - name: User
+    description: |
+      API Calls that perform operations with Plex Media Server Users

pms/pms-spec.yaml

@@ -96,142 +96,99 @@ paths:
   # Plex Media Server endpoints
 
   /:
-    $ref: "./paths/pms/root.yaml"
+    $ref: "./paths/root.yaml"
   /:/prefs:
-    $ref: "./paths/pms/server-preferences.yaml"
+    $ref: "./paths/server-preferences.yaml"
 
   /activities:
-    $ref: "./paths/pms/activities.yaml"
+    $ref: "./paths/activities.yaml"
   /activities/{activityUUID}:
-    $ref: "./paths/pms/activities-cancel.yaml"
+    $ref: "./paths/activities-cancel.yaml"
   /butler:
-    $ref: "./paths/pms/butler.yaml"
+    $ref: "./paths/butler.yaml"
   /butler/{taskName}:
-    $ref: "./paths/pms/butler-task.yaml"
+    $ref: "./paths/butler-task.yaml"
   /clients:
-    $ref: "./paths/pms/clients.yaml"
+    $ref: "./paths/clients.yaml"
 
   /hubs:
-    $ref: "./paths/pms/hubs.yaml"
+    $ref: "./paths/hubs.yaml"
   /hubs/search:
-    $ref: "./paths/pms/hubs-search.yaml"
+    $ref: "./paths/hubs-search.yaml"
   /hubs/search/voice:
-    $ref: "./paths/pms/hubs-search-voice.yaml"
+    $ref: "./paths/hubs-search-voice.yaml"
   /hubs/sections/{sectionId}:
-    $ref: "./paths/pms/hubs-section.yaml"
+    $ref: "./paths/hubs-section.yaml"
 
   /identity:
-    $ref: "./paths/pms/identity.yaml"
+    $ref: "./paths/identity.yaml"
 
   /library/hashes:
-    $ref: "./paths/pms/library-hashes.yaml"
+    $ref: "./paths/library-hashes.yaml"
   /library/recentlyAdded:
-    $ref: "./paths/pms/library-recentlyadded.yaml"
+    $ref: "./paths/library-recentlyadded.yaml"
   /library/sections:
-    $ref: "./paths/pms/all-libraries.yaml"
+    $ref: "./paths/all-libraries.yaml"
   /library/sections/{sectionId}:
-    $ref: "./paths/pms/library-details.yaml"
+    $ref: "./paths/library-details.yaml"
   /library/sections/{sectionId}/all:
-    $ref: "./paths/pms/library-content-all.yaml"
+    $ref: "./paths/library-content-all.yaml"
   /library/sections/{sectionId}/refresh:
-    $ref: "./paths/pms/library-refresh.yaml"
+    $ref: "./paths/library-refresh.yaml"
   /library/sections/{sectionId}/latest:
-    $ref: "./paths/pms/library-content-latest.yaml"
+    $ref: "./paths/library-content-latest.yaml"
   /library/sections/{sectionId}/common:
-    $ref: "./paths/pms/library-content-common.yaml"
+    $ref: "./paths/library-content-common.yaml"
   /library/onDeck:
-    $ref: "./paths/pms/library-ondeck.yaml"
+    $ref: "./paths/library-ondeck.yaml"
 
   /log:
-    $ref: "./paths/pms/log.yaml"
+    $ref: "./paths/log.yaml"
   /log/networked:
-    $ref: "./paths/pms/log-networked.yaml"
+    $ref: "./paths/log-networked.yaml"
 
   /myplex/account:
-    $ref: "./paths/pms/myplex-account.yaml"
+    $ref: "./paths/myplex-account.yaml"
 
   /photo/:/transcode:
-    $ref: "./paths/pms/photo-transcode.yaml"
+    $ref: "./paths/photo-transcode.yaml"
   /playlists:
-    $ref: "./paths/pms/playlists.yaml"
+    $ref: "./paths/playlists.yaml"
   /playlists/all:
-    $ref: "./paths/pms/all-playlists.yaml"
+    $ref: "./paths/all-playlists.yaml"
   /playlists/{playlistID}:
-    $ref: "./paths/pms/playlist-id.yaml"
+    $ref: "./paths/playlist-id.yaml"
   /playlists/{playlistID}/items:
-    $ref: "./paths/pms/playlist-contents.yaml"
+    $ref: "./paths/playlist-contents.yaml"
   /playlists/upload:
-    $ref: "./paths/pms/playlist-upload.yaml"
+    $ref: "./paths/playlist-upload.yaml"
 
   /search:
-    $ref: "./paths/pms/search.yaml"
+    $ref: "./paths/search.yaml"
   /security/token:
-    $ref: "./paths/pms/security-token.yaml"
+    $ref: "./paths/security-token.yaml"
   /security/resources:
-    $ref: "./paths/pms/security-resources.yaml"
+    $ref: "./paths/security-resources.yaml"
 
   /servers:
-    $ref: "./paths/pms/servers.yaml"
+    $ref: "./paths/servers.yaml"
   /status/sessions:
-    $ref: "./paths/pms/sessions.yaml"
+    $ref: "./paths/sessions.yaml"
   /status/sessions/history/all:
-    $ref: "./paths/pms/session-history.yaml"
+    $ref: "./paths/session-history.yaml"
 
   /transcode/sessions:
-    $ref: "./paths/pms/transcode-sessions.yaml"
+    $ref: "./paths/transcode-sessions.yaml"
   /transcode/sessions/{sessionKey}:
-    $ref: "./paths/pms/transcode-sessions-key.yaml"
+    $ref: "./paths/transcode-sessions-key.yaml"
 
   /updater/status:
-    $ref: "./paths/pms/updater-status.yaml"
+    $ref: "./paths/updater-status.yaml"
   /updater/check:
-    $ref: "./paths/pms/updater-check.yaml"
+    $ref: "./paths/updater-check.yaml"
   /updater/apply:
-    $ref: "./paths/pms/updater-apply.yaml"
+    $ref: "./paths/updater-apply.yaml"
 
-  # Plex.tv API endpoints
-  /companions:
-    servers:
-      - url: https://plex.tv/api/v2
-    $ref: "./paths/plex.tv/companions.yaml"
-  /geoip:
-    servers:
-      - url: https://plex.tv/api/v2
-    $ref: "./paths/plex.tv/geoip.yaml"
-  /home:
-    servers:
-      - url: https://plex.tv/api/v2
-    $ref: "./paths/plex.tv/home.yaml"
-  /pins:
-    servers:
-      - url: https://plex.tv/api/v2
-    $ref: "./paths/plex.tv/pins.yaml"
-  /pins/{pinID}:
-    servers:
-      - url: https://plex.tv/api/v2
-    $ref: "./paths/plex.tv/pins-id.yaml"
-
-  /resources:
-    servers:
-      - url: https://plex.tv/api/v2
-    $ref: "./paths/plex.tv/resources.yaml"
-
-  /user:
-    servers:
-      - url: https://plex.tv/api/v2
-    $ref: "./paths/plex.tv/user.yaml"
-  /user/settings:
-    servers:
-      - url: https://plex.tv/api/v2
-    $ref: "./paths/plex.tv/user-settings.yaml"
-  /user/settings/opt_outs:
-    servers:
-      - url: https://plex.tv/api/v2
-    $ref: "./paths/plex.tv/user-settings-opt_outs.yaml"
-  /rooms:
-    servers:
-      - url: https://together.plex.tv
-    $ref: "./paths/plex.tv/rooms.yaml"
 tags:
   - name: Activities
     description: |

referenced/parameters/X-Plex-Client-Identifier.yaml

@@ -1,6 +0,0 @@
-in: header
-name: X-Plex-Client-Identifier
-description: Unique Id, UUID, serial number, or other number unique per device that identifies your client
-schema:
-  type: string
-required: true

referenced/parameters/X-Plex-Container-Size.yaml

@@ -1,13 +0,0 @@
-  in: header
-  name: X-Plex-Container-Size
-  description: |
-    Paging Size, Number of items to return for a given query. 
-    Commonly referred to as the limit parameter
-  schema:
-    type: number
-    example:
-      - 0
-      - 25
-      - 50
-      - 100
-  required: false

referenced/parameters/X-Plex-Container-Start.yaml

@@ -1,13 +0,0 @@
-  in: header
-  name: X-Plex-Container-Start
-  description: |
-    Paging Start, Number to offset into the total before returning the size for a given query. 
-    Commonly referred to as the offset parameter
-  schema:
-    type: number
-    example:
-      - 0
-      - 25
-      - 50
-      - 100
-  required: false

referenced/parameters/X-Plex-Device-Name.yaml

@@ -1,7 +0,0 @@
-  in: header
-  name: X-Plex-Device-Name
-  description: Primary name for the device eg. `Plex Web (Chrome)`
-  schema:
-    type: string
-    example: Plex Web (Chrome)
-  required: false

referenced/parameters/X-Plex-Device.yaml

@@ -1,12 +0,0 @@
-in: header
-name: X-Plex-Device
-description: |
-  The type of device your application is running on
-  Device name and or model number, eg `iPhone3,2`, `Motorola XOOM™`, `LG5200TV`
-schema:
-  type: string
-  example:
-    - iPhone3,2
-    - Motorola XOOM™
-    - LG5200TV
-required: false

referenced/parameters/X-Plex-Platform-Version.yaml

@@ -1,10 +0,0 @@
-in: header
-name: X-Plex-Platform-Version
-description: Operating system version, eg `4.3.1`, `10.6.7`, `3.2`
-schema:
-  type: string
-  example:
-    - 4.3.1
-    - 10.6.7
-    - 3.2
-required: false

referenced/parameters/X-Plex-Platform.yaml

@@ -1,12 +0,0 @@
-in: header
-name: X-Plex-Platform
-description: Platform name, eg `Web`, `iOS`, `MacOSX`, `Android`, `LG`
-schema:
-  type: string
-  example:
-    - Web
-    - iOS
-    - MacOSX
-    - Android
-    - LG
-required: false

referenced/parameters/X-Plex-Product.yaml

@@ -1,10 +0,0 @@
-in: header
-name: X-Plex-Product
-description: Plex application name, eg `Laika`, `Plex Media Server`, `Media Link`
-schema:
-  type: string
-  example:
-    - Laika
-    - Plex Media Server
-    - Media Link
-required: false

referenced/parameters/X-Plex-Provides.yaml

@@ -1,11 +0,0 @@
-in: header
-name: X-Plex-Provides
-description: One or more of `[player, controller, server]`
-schema:
-  type: string
-  example:
-    - iOS
-    - MacOSX
-    - Android
-    - LG
-required: false

referenced/parameters/X-Plex-Version.yaml

@@ -1,6 +0,0 @@
-in: header
-name: X-Plex-Version
-description: Your application version number
-schema:
-  type: string
-required: false

referenced/parameters/mediaType.yaml

@@ -1,38 +0,0 @@
-name: mediaType
-in: query
-description: |
-        The Plex Media Types for the operation
-        1. Movies
-        2. Shows
-        3. Seasons
-        4. Episodes
-        5. Trailer
-        6. Comic
-        7. Person
-        8. Artist
-        9. Album
-        10. Track
-        11. Photo Album
-        12. Picture
-        13. Photo
-        14. Clip
-        15. Playlist Item
-required: false
-schema:
-  type: integer
-  enum:
-          - 1
-          - 2
-          - 3
-          - 4
-          - 5
-          - 6
-          - 7
-          - 8
-          - 9
-          - 10
-          - 11
-          - 12
-          - 13
-          - 14
-          - 15