Merge pull request #48 from LukeHagar/redocly-lint

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

@@ -13,14 +13,10 @@ jobs:
   dereference_api:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout PR branch
-        uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-
-      - name: Install Dependencies
-        run: bun install
+      - name: Project Setup
+        uses: ./.github/workflows/steps/project-setup
 
       - name: Dereference Plex Media Server Specification
         run: bun run build

.github/workflows/pull-request-checks.yaml

@@ -0,0 +1,55 @@
+name: Checks
+"on":
+  pull_request:
+    paths:
+      - src/**
+      - tests/**
+
+jobs:
+  unit-test:
+    name: Run Unit Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Project Setup
+        uses: ./.github/workflows/steps/project-setup
+
+      - name: Bundle OpenAPI Spec
+        run: bun run build
+
+      - name: Run Unit Tests
+        run: bun run test
+
+  type-check:
+    name: Run Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Project Setup
+        uses: ./.github/workflows/steps/project-setup
+
+      - name: Run Unit Tests
+        run: bun run type-check
+
+  lint:
+    name: Run OpenApi Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Project Setup
+        uses: ./.github/workflows/steps/project-setup
+
+      - name: OpenAPI Lint
+        run: bun run lint
+
+      - name: Install Speakeasy CLI
+        run: bun run setup-speakeasy-cli
+
+      - name: Bundle OpenAPI Spec
+        run: bun run build
+
+      - name: OpenAPI Lint On Bundled Spec
+        run: bun run lint-bundled

.github/workflows/steps/project-setup/action.yaml

@@ -0,0 +1,12 @@
+name: 'Project Setup'
+description: 'Setup Bun and install dependencies'
+runs:
+  using: 'composite'
+  steps:
+    -   name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "latest"
+    -   name: Clean install node_modules
+        shell: bash
+        run: bun install

package.json

@@ -3,24 +3,25 @@
   "version": "1.0.0",
   "description": "An open source Plex Media Server API Specification",
   "main": "src/pms-spec.yaml",
+  "author": "LukeHagar",
+  "keywords": ["plex", "api", "specification", "openapi", "swagger"],
+  "license": "MIT",
   "scripts": {
     "dev": "redocly preview -d=./src",
     "preview-docs": "redocly preview-docs src/pms-spec.yaml --config=./redocly.yaml",
     "stats": "redocly stats ./src/pms-spec.yaml",
     "build": "swagger-cli bundle --dereference ./src/pms-spec.yaml -t yaml -o ./output/plex-media-server-spec-dereferenced.yaml",
     "build-redocly": "redocly bundle ./src/pms-spec.yaml --ext yaml  -o ./output/plex-media-server-spec-dereferenced.yaml",
     "test": "bun run build && vitest --run",
+    "type-check": "tsc",
     "setup-speakeasy-cli": "curl -fsSL https://raw.githubusercontent.com/speakeasy-api/speakeasy/main/install.sh | sh",
-    "lint": "speakeasy lint openapi -s ./src/pms-spec.yaml",
+    "lint": "redocly lint",
+    "lint-speakeasy": "speakeasy lint openapi -s ./src/pms-spec.yaml",
     "lint-bundled": "speakeasy lint openapi -s ./output/plex-media-server-spec-dereferenced.yaml"
   },
-  "keywords": ["plex", "api", "specification", "openapi", "swagger"],
-  "author": "LukeHagar",
-  "license": "ISC",
   "devDependencies": {
     "@modyfi/vite-plugin-yaml": "^1.1.0",
     "@redocly/cli": "latest",
-    "@scalar/cli": "^0.2.190",
     "@types/node": "^22.5.0",
     "swagger-cli": "^4.0.4",
     "typescript": "^5.5.4",

redocly.yaml

@@ -1,2 +1,9 @@
 extends:
-  - recommended
+  - recommended-strict
+
+apis:
+  core@v1:
+    root: ./src/pms-spec.yaml
+
+rules:
+  no-ambiguous-paths: off

src/parameters/container-size.yaml

@@ -1,10 +1,12 @@
 name: X-Plex-Container-Size
 in: query
 description: |
-  Add the length/size of the number of media to be retrieved.
+  The number of items to return. If not specified, all items will be returned.
+  If the number of items exceeds the limit, the response will be paginated.
   By default this is 50
 schema:
   type: integer
+  format: int32
   default: 50
   example: 50
 required: false

src/parameters/container-start.yaml

@@ -1,10 +1,12 @@
 name: X-Plex-Container-Start
 in: query
 description: |
-  Add the index start from which the media items should be returned.
+  The index of the first item to return. If not specified, the first item will be returned.
+  If the number of items exceeds the limit, the response will be paginated.
   By default this is 0
 schema:
   type: integer
+  format: int32
   default: 0
   example: 0
 required: false

src/parameters/library/section-key.yaml

@@ -0,0 +1,11 @@
+name: sectionKey
+description: | 
+  The unique key of the Plex library. 
+  Note: This is unique in the context of the Plex server.
+in: path
+schema:
+  type: integer
+  format: int32
+  example: 9518
+required: true
+

src/paths/library/[sectionKey]/delete-library.yaml

@@ -0,0 +1,15 @@
+delete:
+  tags:
+    - Library
+  summary: Delete Library Section
+  description: Delete a library using a specific section id
+  operationId: deleteLibrary
+  parameters:
+    - $ref: "../../../parameters/library/section-key.yaml"
+  responses:
+    "200":
+      description: The library is deleted
+    "400":
+      $ref: "../../../responses/400.yaml"
+    "401":
+      $ref: "../../../responses/401.yaml"

src/paths/library/[sectionId]/get-and-delete-library-details.yaml → src/paths/library/[sectionKey]/get-library-details.yaml

@@ -45,13 +45,7 @@ get:
 
   operationId: get-library-details
   parameters:
-    - name: sectionId
-      description: The id of the library
-      in: path
-      schema:
-        type: number
-        example: 15
-      required: true
+    - $ref: "../../../parameters/library/section-key.yaml"
     - name: includeDetails
       description: |
         Whether or not to include details for a section (types, filters, and sorts). 
@@ -64,7 +58,6 @@ get:
           - 1
         default: 0
       required: false
-
   responses:
     "200":
       description: The details of the library
@@ -236,26 +229,3 @@ get:
       $ref: "../../../responses/400.yaml"
     "401":
       $ref: "../../../responses/401.yaml"
-
-# TODO Move the deleteLibrary operation to its own file, there is currently a bug in the SDKEasy lint that prevents this referencing two methods from the same path url
-delete:
-  tags:
-    - Library
-  summary: Delete Library Section
-  description: Delete a library using a specific section id
-  operationId: deleteLibrary
-  parameters:
-    - name: sectionId
-      description: The id of the library
-      in: path
-      schema:
-        type: number
-        example: 15
-      required: true
-  responses:
-    "200":
-      description: The library is deleted
-    "400":
-      $ref: "../../../responses/400.yaml"
-    "401":
-      $ref: "../../../responses/401.yaml"

src/paths/library/[sectionId]/get-library-items.yaml → src/paths/library/[sectionKey]/get-library-items.yaml

@@ -25,12 +25,7 @@ get:
     - `firstCharacter`: Items categorized by the first letter.
     - `folder`: Items categorized by folder.
   parameters:
-    - name: sectionId
-      in: path
-      required: true
-      description: the Id of the library to query
-      schema:
-        type: [integer, string]
+    - $ref: "../../../parameters/library/section-key.yaml"
     - name: tag
       in: path
       required: true

src/paths/library/[sectionId]/get-search-library.yaml → src/paths/library/[sectionKey]/get-search-library.yaml

@@ -23,12 +23,7 @@ get:
 
     > **Note**: Filters and sorts are optional; without them, no filtering controls are rendered.
   parameters:
-    - name: sectionId
-      in: path
-      required: true
-      description: the Id of the library to query
-      schema:
-        type: integer
+    - $ref: "../../../parameters/library/section-key.yaml"
     - $ref: "../../../parameters/accept-application-json.yaml"
     - $ref: "../../../parameters/type.yaml"
   responses:

src/paths/library/[sectionId]/refresh/get-refresh-library-metadata.yaml → src/paths/library/[sectionKey]/refresh/get-refresh-library-metadata.yaml

@@ -6,13 +6,7 @@ get:
     This endpoint Refreshes all the Metadata of the library.
   operationId: get-refresh-library-metadata
   parameters:
-    - name: sectionId
-      description: The id of the library
-      in: path
-      schema:
-        type: number
-        example: 15
-      required: true
+    - $ref: "../../../../parameters/library/section-key.yaml"
     - name: force
       description: Force the refresh even if the library is already being refreshed.
       in: query

src/paths/library/content-top.yaml

@@ -6,29 +6,17 @@ get:
     This endpoint will return the top watched content from libraries of a certain type
   operationId: getTopWatchedContent
   parameters:
-    - name: type
-      description: the library type (1 - movies, 2 - shows, 3 - music)
-      in: query
-      schema:
-        type: integer
-      required: true
-      examples:
-        movies:
-          value: 1
-        shows:
-          value: 2
-        music:
-          value: 3
+    - $ref: "../../parameters/type.yaml"
     - name: includeGuids
       in: query
       description: |
         Adds the Guids object to the response
-      schema: 
+      schema:
         type: integer
       required: false
-      example: 1           
+      example: 1
   responses:
-    "200": 
+    "200":
       description: The metadata of the library item.
       content:
         application/json:
@@ -69,7 +57,7 @@ get:
                         guid:
                           type: string
                           example: plex://movie/5d77683f6f4521001ea9dc53
-                        slug: 
+                        slug:
                           type: string
                           example: waterloo-road
                         studio:
@@ -220,7 +208,11 @@ get:
                           items:
                             type: object
                             properties:
-                              id: 
+                              id:
                                 type: integer
                                 format: int32
-                                example: 220
+                                example: 220
+    "400":
+      $ref: "../../responses/400.yaml"
+    "401":
+      $ref: "../../responses/401.yaml"

src/paths/library/metadata/[ratingKey]/banner/get-banner-image.yaml

@@ -80,3 +80,7 @@ get:
           schema:
             type: string
             format: binary
+    "400":
+      $ref: "../../../../../responses/400.yaml"
+    "401":
+      $ref: "../../../../../responses/401.yaml"

src/paths/library/metadata/[ratingKey]/thumb/get-thumb-image.yaml

@@ -80,3 +80,7 @@ get:
           schema:
             type: string
             format: binary
+    "400":
+      $ref: "../../../../../responses/400.yaml"
+    "401":
+      $ref: "../../../../../responses/401.yaml"