Skip to content

Migrate spec docs and tooling from plexapi-dev-docs #119

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
LukasParke wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Migrate spec docs and tooling from plexapi-dev-docs #119

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
134e2e4
docs(tooling): migrate spec docs and validation tooling from plexapi-…
LukasParke Jun 13, 2026
8b4cce2
fix(spec): resolve OpenAPI validation blockers
LukasParke Jun 13, 2026
82149ba
fix(spec): also make spec pass swagger-parser strict validation
LukasParke Jun 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions .github/workflows/spec-validate.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
name: Validate canonical OpenAPI spec

on:
push:
branches: [main]
pull_request:
branches: [main]

jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- name: Install pnpm
uses: pnpm/action-setup@v4
with:
version: 10.18.1

- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
Comment on lines +13 to +24

@coderabbitai coderabbitai Bot Jun 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial | ⚡ Quick win

I humbly suggest pinning GitHub Actions to commit SHAs for enhanced security.

If I may be so bold, the static analysis tool has raised a pertinent security consideration. The workflow presently references actions by tag (e.g., @v4), which, whilst convenient, does present a theoretical supply-chain vulnerability should a tag be moved.

The security-conscious approach would be to pin to specific commit SHAs, thus ensuring immutability.

🔐 Proposed enhancement for supply-chain security 
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
+      - uses: pnpm/action-setup@fe02b34f77f8bc703788d5817da081398fad5dd2 # v4.0.0

-      - name: Set up Node.js
-        uses: actions/setup-node@v4
+      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- uses: actions/checkout@v4
- name: Install pnpm
uses: pnpm/action-setup@v4
with:
version: 10.18.1
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
- name: Install pnpm
uses: pnpm/action-setup@fe02b34f77f8bc703788d5817da081398fad5dd2 # v4.0.0
with:
version: 10.18.1
- name: Set up Node.js
uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
with:
node-version: 20
cache: pnpm
🧰 Tools
🪛 zizmor (1.25.2)

[warning] 13-13: credential persistence through GitHub Actions artifacts (artipacked): does not set persist-credentials: false

(artipacked)

[error] 13-13: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)

[error] 16-16: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)

[error] 21-21: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/spec-validate.yml around lines 13 - 24, The workflow uses
mutable tags for third-party actions (actions/checkout@v4, pnpm/action-setup@v4,
actions/setup-node@v4); pin each action reference to its immutable commit SHA
instead (e.g., replace actions/checkout@v4 with actions/checkout@<commit-sha>,
pnpm/action-setup@v4 with pnpm/action-setup@<commit-sha>, and
actions/setup-node@v4 with actions/setup-node@<commit-sha>) by looking up the
exact commit SHA from each action's GitHub repo/releases and updating the yml
entries accordingly so the workflow uses fixed SHAs.


- name: Install dependencies
run: pnpm install --frozen-lockfile

- name: Validate OpenAPI spec
run: pnpm spec:validate

- name: Check generated reference is up to date
run: |
pnpm spec:generate-reference
git diff --exit-code docs/endpoints.md

- name: Dry-run breaking-change detection
run: pnpm spec:diff
Comment on lines +1 to +38

@coderabbitai coderabbitai Bot Jun 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial | 💤 Low value

One might consider explicit permissions for enhanced security posture.

Whilst the workflow functions admirably, I note with respect that it relies upon default permissions. Best practices suggest explicitly declaring minimal required permissions, typically contents: read for such validation workflows.

This is, of course, an optional refinement rather than a pressing concern.

🔒 Proposed explicit permissions declaration 
 name: Validate canonical OpenAPI spec

 on:
   push:
     branches: [main]
   pull_request:
     branches: [main]

+permissions:
+  contents: read
+
 jobs:
   validate:
     runs-on: ubuntu-latest
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
name: Validate canonical OpenAPI spec
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install pnpm
uses: pnpm/action-setup@v4
with:
version: 10.18.1
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
- name: Install dependencies
run: pnpm install --frozen-lockfile
- name: Validate OpenAPI spec
run: pnpm spec:validate
- name: Check generated reference is up to date
run: |
pnpm spec:generate-reference
git diff --exit-code docs/endpoints.md
- name: Dry-run breaking-change detection
run: pnpm spec:diff
name: Validate canonical OpenAPI spec
on:
push:
branches: [main]
pull_request:
branches: [main]
permissions:
contents: read
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install pnpm
uses: pnpm/action-setup@v4
with:
version: 10.18.1
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
- name: Install dependencies
run: pnpm install --frozen-lockfile
- name: Validate OpenAPI spec
run: pnpm spec:validate
- name: Check generated reference is up to date
run: |
pnpm spec:generate-reference
git diff --exit-code docs/endpoints.md
- name: Dry-run breaking-change detection
run: pnpm spec:diff
🧰 Tools
🪛 zizmor (1.25.2)

[warning] 13-13: credential persistence through GitHub Actions artifacts (artipacked): does not set persist-credentials: false

(artipacked)

[warning] 1-39: overly broad permissions (excessive-permissions): default permissions used due to no permissions: block

(excessive-permissions)

[error] 13-13: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)

[error] 16-16: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)

[error] 21-21: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)

[info] 10-10: workflow or action definition without a name (anonymous-definition): this job

(anonymous-definition)

[warning] 3-7: insufficient job-level concurrency limits (concurrency-limits): workflow is missing concurrency setting

(concurrency-limits)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/spec-validate.yml around lines 1 - 38, The workflow "name:
Validate canonical OpenAPI spec" currently relies on default permissions; add an
explicit minimal permissions block at the top of the workflow YAML (adjacent to
the existing name/on keys) such as "permissions: contents: read" to restrict
access, ensuring the jobs (including the "validate" job and its steps like
"Validate OpenAPI spec" and "Check generated reference is up to date") run with
least privilege.

10 changes: 10 additions & 0 deletions .spectral.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
extends: ["spectral:oas"]

rules:
operation-operationId: error
operation-description: warn
operation-tags: error
operation-tag-defined: error
openapi-tags: warn
info-contact: warn
info-license: warn
33 changes: 28 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,33 @@
# Plex Media Server OpenAPI Specification

An Open Source OpenAPI Specification for Plex Media Server
An open source OpenAPI 3.1 specification for the Plex Media Server API.

Automation and SDKs provided by [Speakeasy](https://speakeasyapi.dev/)
- **Live docs:** [plexapi.dev](https://plexapi.dev)
- **Docs repository:** [LukasParke/plex-mintlify-docs](https://github.com/LukasParke/plex-mintlify-docs)
- **Original developer docs (being consolidated):** [LukasParke/plexapi-dev-docs](https://github.com/LukasParke/plexapi-dev-docs)

## Documentation
## What's in this repository

[API Documentation](https://plexapi.dev)
| File / directory | Purpose |
|------------------|---------|
| `plex-api-spec.yaml` | Canonical OpenAPI 3.1 contract for the Plex Media Server API. |
| `docs/` | Contributor documentation: contract decisions and SDK generation strategy. |
| `scripts/` | Validation, lint, diff, and reference-generation tooling. |
| `.github/workflows/spec-validate.yml` | CI that validates the spec on every PR and push to `main`. |

## Validation

```bash
pnpm install
pnpm spec:validate
pnpm spec:lint
pnpm spec:diff
```

## SDKs

The following SDKs are generated from the OpenAPI Specification. They are automatically generated and may not be fully tested. If you find any issues, please open an issue on the respective repository.
Automation and SDKs are provided by [Speakeasy](https://www.speakeasyapi.dev/).
The following community SDKs are generated from this specification:

| Language | Repository | Releases | Other |
| --------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
Expand All @@ -22,3 +39,9 @@ The following SDKs are generated from the OpenAPI Specification. They are automa
| PHP | [GitHub](https://github.com/LukeHagar/plexphp) | [Releases](https://github.com/LukeHagar/plexphp/releases) | - |
| Java | [GitHub](https://github.com/LukeHagar/plexjava) | [Releases](https://github.com/LukeHagar/plexjava/releases) | - |
| C# | [GitHub](https://github.com/LukeHagar/plexcsharp) | [Releases](https://github.com/LukeHagar/plexcsharp/releases) | - |

## Contributing

See [docs/api-contract.md](./docs/api-contract.md) and [docs/sdk-generation-strategy.md](./docs/sdk-generation-strategy.md) for design context.

To propose changes to the spec, open a pull request. The CI check `spec:validate` must pass before merge.
40 changes: 40 additions & 0 deletions docs/api-contract.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Plex API Contract

## Decision: OpenAPI 3.1

PlexAPI.dev describes the Plex Media Server HTTP API as a curated, versioned [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0.html) contract. This decision is aligned with the [SDK generation strategy](./sdk-generation-strategy), which calls for a single source of truth that feeds both reference documentation and SDK generation.

### Why OpenAPI 3.1

| Consideration | Rationale |
|---------------|-----------|
| **Tooling maturity** | OpenAPI 3.1 is supported by Swagger Parser, OpenAPI Generator, Spectral, and many documentation generators. |
| **JSON Schema alignment** | OpenAPI 3.1 schemas are valid JSON Schema 2020-12 drafts, making it easy to reuse models for validation and SDK types. |
| **SDK generation** | OpenAPI Generator and Microsoft Kiota both consume OpenAPI 3.1, matching the hybrid SDK strategy. |
| **Documentation generation** | Reference pages can be generated or hand-written from the same contract, keeping docs and code in sync. |

## Contract location

The canonical contract lives at:

```text
plex-api-spec.yaml
```

This file is the single source of truth for the Plex Media Server API. The [PlexAPI.dev documentation site](https://plexapi.dev) and the community SDKs consume this contract.

## Validation

The contract is validated on every change via:

```bash
pnpm install
pnpm spec:validate
pnpm spec:lint
```

## Security notes

- The contract declares `X-Plex-Token` as an `apiKey` security scheme.
- Token values are never included in the spec or generated examples.
- Examples and guides instruct users to load tokens from environment variables or secure configuration.
Loading
Loading