Skip to content

feat(cli): add x-fern-playground-description for playground-only auth docs - #17665

Draft
adidavid014 wants to merge 1 commit into
mainfrom
devin/1788554526-playground-auth-description
Draft

feat(cli): add x-fern-playground-description for playground-only auth docs#17665
adidavid014 wants to merge 1 commit into
mainfrom
devin/1788554526-playground-auth-description

Conversation

@adidavid014

Copy link
Copy Markdown
Contributor

Description

Lets a customer author auth guidance that only shows in the API Playground (under the token input), without touching the API reference's Authorization description.

components:
  securitySchemes:
    dropboxTeamAuth:
      description: Team-level OAuth 2.0 token…      # unchanged → API reference
      x-fern-playground-description: |             # new → playground only
        To mint a token, see [Testing with a generated token](https://docs.dropboxapi.com/…)

Fern definition equivalent: auth-schemes.<name>.playground-docs.

Flow: x-fern-playground-description / playground-docs → IR AuthScheme.playgroundDocs (optional) → FDR playgroundDescription on bearerAuth / basicAuth / header. docs/description are untouched, so the reference page and the collapsed playground auth header keep their existing text.

Rendering side is fern-api/fern-platform#14486 (adds playgroundDescription to the FDR zod schemas and renders it as a callout under the input). This PR's @fern-api/fern-platform-published fdr-sdk types don't have playgroundDescription yet, so @fern-api/register#compile fails until that PR merges and the SDK is bumped — hence draft.

Changes Made

  • IR: BaseAuthScheme.playgroundDocs?: string, VERSION 67.23.067.24.0, changelog entry, regenerated SDK. Additive/optional → no migration.
  • OpenAPI 3.1 converter reads the extension for bearer/basic/header/oauth; OAuth endpoint resolution preserves it.
  • Fern definition schema: new WithPlaygroundDocsSchema mixed into header/basic/bearer/inferred/oauth schemes; both convertApiAuth converters pass it through.
  • ir-to-fdr-converter: maps playgroundDocsplaygroundDescription (bearer/basic/header + inferred and OAuth bearer fallbacks).
  • CLI changelog entry under changes/unreleased/.
  • Not changed: the legacy openapi-ir-parser v3 convertSecurityScheme path, which already drops the security scheme description entirely.

Testing

  • Unit tests added/updated — new fixture auth-playground-description in register/src/ir-to-fdr-converter/__test__ asserting IR playgroundDocs and FDR playgroundDescription coexist with description; auth snapshots updated.
  • Manual testing completed — end-to-end browser verification of the rendered callout happens on the fern-platform PR.

Link to Devin session: https://app.devin.ai/sessions/6a812925d9ba495aa86d3cc6a6f3f7b0
Open in Devin Desktop: https://app.devin.ai/desktop/session/6a812925d9ba495aa86d3cc6a6f3f7b0?variant=devin
Requested by: @adidavid014

… docs

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@devin-ai-integration

Copy link
Copy Markdown
Contributor

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment, CI, and merge conflict monitoring

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant