diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 000000000..5c0f84461 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,25 @@ +# Configures Dependabot to keep our GitHub Actions pinned references up to date. +# Other ecosystems are intentionally not enabled here. +# +# Pair with the `unpinned-uses` policy enforced by `.github/workflows/zizmor.yml`: +# zizmor requires actions to be pinned to a full-length commit SHA with the +# version tag as a trailing comment. Dependabot will keep both in sync. +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + groups: + actions: + patterns: + - "*" + cooldown: + default-days: 14 + open-pull-requests-limit: 1 + commit-message: + prefix: "ci" + include: "scope" + labels: + - "dependencies" + - "github-actions" diff --git a/.github/workflows/auto-merge-on-docs-release.yml b/.github/workflows/auto-merge-on-docs-release.yml index a79dad075..91ca21ec8 100644 --- a/.github/workflows/auto-merge-on-docs-release.yml +++ b/.github/workflows/auto-merge-on-docs-release.yml @@ -9,7 +9,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Find and merge dependent PRs - uses: actions/github-script@v8 + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8 with: script: | const version = context.payload.client_payload.version; @@ -47,4 +47,4 @@ jobs: console.log(`Merged PR #${pr.number}: ${pr.title}`); } } - } \ No newline at end of file + } diff --git a/.github/workflows/check-devin-pr-assignee.yml b/.github/workflows/check-devin-pr-assignee.yml index ccba24823..9d9af64ab 100644 --- a/.github/workflows/check-devin-pr-assignee.yml +++ b/.github/workflows/check-devin-pr-assignee.yml @@ -13,7 +13,7 @@ jobs: if: ${{ github.event.pull_request.user.login == 'devin-ai-integration[bot]' }} steps: - name: Auto-assign requester from PR description - uses: actions/github-script@v8 + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8 with: github-token: ${{ secrets.GITHUB_TOKEN }} script: | diff --git a/.github/workflows/check-links.yml b/.github/workflows/check-links.yml index 2ddf259d9..c2491b01a 100644 --- a/.github/workflows/check-links.yml +++ b/.github/workflows/check-links.yml @@ -16,7 +16,9 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v5 + uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5 + with: + persist-credentials: false - name: Create lychee config run: | @@ -380,7 +382,7 @@ jobs: - name: Upload URLs (early, for debugging) - uses: actions/upload-artifact@v6 + uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6 with: name: urls path: | @@ -392,7 +394,7 @@ jobs: - name: Check GitHub links (very low concurrency to avoid 503 rate limiting) id: lychee_github if: steps.extract_github_http.outputs.github_http_count != '0' - uses: lycheeverse/lychee-action@v2 + uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2 with: args: >- --no-progress @@ -408,7 +410,7 @@ jobs: - name: Check non-GitHub links (high concurrency) id: lychee_main - uses: lycheeverse/lychee-action@v2 + uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2 with: args: >- --config lychee.toml @@ -600,15 +602,15 @@ jobs: broken_count=$(wc -l < broken-links.txt | tr -d ' ') # Get rate limit stats - rate_limited="${{ steps.retry429.outputs.rate_limited_count }}" + rate_limited="${STEPS_RETRY429_OUTPUTS_RATE_LIMITED_COUNT}" rate_limited=${rate_limited:-0} - still_failing_429="${{ steps.retry429.outputs.still_failing_429 }}" + still_failing_429="${STEPS_RETRY429_OUTPUTS_STILL_FAILING_429}" still_failing_429=${still_failing_429:-0} # Get GitHub local verification stats - github_verified="${{ steps.verify_github.outputs.verified_count }}" + github_verified="${STEPS_VERIFY_GITHUB_OUTPUTS_VERIFIED_COUNT}" github_verified=${github_verified:-0} - github_missing="${{ steps.verify_github.outputs.missing_count }}" + github_missing="${STEPS_VERIFY_GITHUB_OUTPUTS_MISSING_COUNT}" github_missing=${github_missing:-0} # Build clean errors-only report @@ -682,9 +684,9 @@ jobs: cat lychee-summary-table.md echo "" # Get repo-internal GitHub URL counts - verified_locally="${{ steps.retry429.outputs.verified_locally }}" + verified_locally="${STEPS_RETRY429_OUTPUTS_VERIFIED_LOCALLY}" verified_locally=${verified_locally:-0} - missing_locally="${{ steps.retry429.outputs.missing_locally }}" + missing_locally="${STEPS_RETRY429_OUTPUTS_MISSING_LOCALLY}" missing_locally=${missing_locally:-0} echo "Recovery Info:" @@ -763,10 +765,17 @@ jobs: echo "" } >> "$GITHUB_STEP_SUMMARY" + env: + STEPS_RETRY429_OUTPUTS_RATE_LIMITED_COUNT: ${{ steps.retry429.outputs.rate_limited_count }} + STEPS_RETRY429_OUTPUTS_STILL_FAILING_429: ${{ steps.retry429.outputs.still_failing_429 }} + STEPS_VERIFY_GITHUB_OUTPUTS_VERIFIED_COUNT: ${{ steps.verify_github.outputs.verified_count }} + STEPS_VERIFY_GITHUB_OUTPUTS_MISSING_COUNT: ${{ steps.verify_github.outputs.missing_count }} + STEPS_RETRY429_OUTPUTS_VERIFIED_LOCALLY: ${{ steps.retry429.outputs.verified_locally }} + STEPS_RETRY429_OUTPUTS_MISSING_LOCALLY: ${{ steps.retry429.outputs.missing_locally }} - name: Upload errors-only report if: always() - uses: actions/upload-artifact@v6 + uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6 with: name: lychee-report path: ./lychee-report.md @@ -774,7 +783,7 @@ jobs: - name: Upload lychee outputs and verification results if: always() - uses: actions/upload-artifact@v6 + uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6 with: name: lychee-outputs path: | @@ -787,7 +796,7 @@ jobs: - name: Create PR for broken links id: create-pr if: steps.check_failures.outputs.has_other_failures == 'true' || steps.retry429.outputs.has_429_failures == 'true' || steps.verify_github.outputs.has_missing == 'true' - uses: actions/github-script@v8 + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8 env: DEVIN_PROMPT: | @devin-ai-integration Please fix the broken links detected by the scheduled link checker. @@ -1042,7 +1051,7 @@ jobs: - name: Send Slack notification for broken links if: steps.create-pr.outputs.pr_created == 'true' - uses: actions/github-script@v8 + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8 env: SLACK_TOKEN: ${{ secrets.DEVIN_AI_PR_BOT_SLACK_TOKEN }} PR_URL: ${{ steps.create-pr.outputs.pr_url }} @@ -1085,14 +1094,18 @@ jobs: if: steps.check_failures.outputs.has_other_failures == 'true' || steps.retry429.outputs.has_429_failures == 'true' || steps.verify_github.outputs.has_missing == 'true' run: | echo "Link check failed!" - if [ "${{ steps.check_failures.outputs.has_other_failures }}" == "true" ]; then + if [ "${STEPS_CHECK_FAILURES_OUTPUTS_HAS_OTHER_FAILURES}" == "true" ]; then echo "There are broken links (non-429 failures) in the report." fi - if [ "${{ steps.retry429.outputs.has_429_failures }}" == "true" ]; then + if [ "${STEPS_RETRY429_OUTPUTS_HAS_429_FAILURES}" == "true" ]; then echo "Some URLs still returned 429 after exponential backoff retry." echo "These URLs may need to be excluded or the rate limit needs more time to reset." fi - if [ "${{ steps.verify_github.outputs.has_missing }}" == "true" ]; then + if [ "${STEPS_VERIFY_GITHUB_OUTPUTS_HAS_MISSING}" == "true" ]; then echo "Some GitHub URLs point to paths that don't exist in the repos." fi exit 1 + env: + STEPS_CHECK_FAILURES_OUTPUTS_HAS_OTHER_FAILURES: ${{ steps.check_failures.outputs.has_other_failures }} + STEPS_RETRY429_OUTPUTS_HAS_429_FAILURES: ${{ steps.retry429.outputs.has_429_failures }} + STEPS_VERIFY_GITHUB_OUTPUTS_HAS_MISSING: ${{ steps.verify_github.outputs.has_missing }} diff --git a/.github/workflows/fern-scribe.yml b/.github/workflows/fern-scribe.yml index cc4888039..1881eda78 100644 --- a/.github/workflows/fern-scribe.yml +++ b/.github/workflows/fern-scribe.yml @@ -16,12 +16,13 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v5 + uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5 with: token: ${{ secrets.GITHUB_TOKEN }} + persist-credentials: false - name: Setup Node.js - uses: actions/setup-node@v5 + uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5 with: node-version: '20' cache: 'npm' @@ -62,7 +63,7 @@ jobs: - name: Comment on issue if: success() - uses: actions/github-script@v8 + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8 with: script: | github.rest.issues.createComment({ @@ -74,7 +75,7 @@ jobs: - name: Comment on failure if: failure() - uses: actions/github-script@v8 + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8 with: script: | github.rest.issues.createComment({ @@ -82,4 +83,4 @@ jobs: owner: context.repo.owner, repo: context.repo.repo, body: '❌ **Fern Scribe encountered an error**\n\nThere was an issue processing your documentation request. Please check the action logs and try again.\n\nIf the problem persists, please contact the maintainers.' - }); \ No newline at end of file + }); diff --git a/.github/workflows/preview-docs.yml b/.github/workflows/preview-docs.yml index 675808397..120026615 100644 --- a/.github/workflows/preview-docs.yml +++ b/.github/workflows/preview-docs.yml @@ -1,32 +1,50 @@ name: Preview Docs on: - pull_request_target: + pull_request: types: [opened, synchronize, ready_for_review] branches: - main jobs: run: + if: github.event.pull_request.head.repo.full_name == github.repository runs-on: ubuntu-latest permissions: pull-requests: write # Only for commenting contents: read # For checking out code steps: + - name: Check for FERN_TOKEN + id: check-token + env: + FERN_TOKEN: ${{ secrets.FERN_TOKEN }} + run: | + if [ -z "$FERN_TOKEN" ]; then + echo "FERN_TOKEN is not available (e.g. Dependabot PRs). Skipping preview." + echo "has_token=false" >> $GITHUB_OUTPUT + else + echo "has_token=true" >> $GITHUB_OUTPUT + fi + - name: Checkout repository - uses: actions/checkout@v5 + if: steps.check-token.outputs.has_token == 'true' + uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5 with: fetch-depth: 0 # Fetch full history for git diff + persist-credentials: false - name: Checkout PR + if: steps.check-token.outputs.has_token == 'true' run: | git fetch origin pull/${{ github.event.pull_request.number }}/head:pr-${{ github.event.pull_request.number }} git checkout pr-${{ github.event.pull_request.number }} - name: Setup Fern CLI - uses: fern-api/setup-fern-cli@v1 + if: steps.check-token.outputs.has_token == 'true' + uses: fern-api/setup-fern-cli@d07601425e9c9ede8745d71ca75c4c462d98755d # v1 - name: Generate preview URL + if: steps.check-token.outputs.has_token == 'true' id: generate-docs env: FERN_TOKEN: ${{ secrets.FERN_TOKEN }} @@ -39,11 +57,13 @@ jobs: echo "Preview URL: $URL" - name: Get page links for changed MDX files + if: steps.check-token.outputs.has_token == 'true' id: page-links env: FERN_TOKEN: ${{ secrets.FERN_TOKEN }} + STEPS_GENERATE_DOCS_OUTPUTS_PREVIEW_URL: ${{ steps.generate-docs.outputs.preview_url }} run: | - PREVIEW_URL="${{ steps.generate-docs.outputs.preview_url }}" + PREVIEW_URL="${STEPS_GENERATE_DOCS_OUTPUTS_PREVIEW_URL}" CHANGED_FILES=$(git diff --name-only origin/main...HEAD -- '*.mdx' 2>/dev/null || echo "") if [ -z "$CHANGED_FILES" ] || [ -z "$PREVIEW_URL" ]; then @@ -67,17 +87,22 @@ jobs: fi - name: Create comment content + if: steps.check-token.outputs.has_token == 'true' run: | - echo ":herb: **Preview your docs:** <${{ steps.generate-docs.outputs.preview_url }}>" > comment.md + echo ":herb: **Preview your docs:** <${STEPS_GENERATE_DOCS_OUTPUTS_PREVIEW_URL}>" > comment.md - if [ -n "${{ steps.page-links.outputs.page_links }}" ]; then + if [ -n "${STEPS_PAGE_LINKS_OUTPUTS_PAGE_LINKS}" ]; then echo "" >> comment.md echo "Here are the markdown pages you've updated:" >> comment.md - echo "${{ steps.page-links.outputs.page_links }}" >> comment.md + echo "${STEPS_PAGE_LINKS_OUTPUTS_PAGE_LINKS}" >> comment.md fi + env: + STEPS_GENERATE_DOCS_OUTPUTS_PREVIEW_URL: ${{ steps.generate-docs.outputs.preview_url }} + STEPS_PAGE_LINKS_OUTPUTS_PAGE_LINKS: ${{ steps.page-links.outputs.page_links }} - name: Post PR comment - uses: thollander/actions-comment-pull-request@v2.4.3 + if: steps.check-token.outputs.has_token == 'true' + uses: thollander/actions-comment-pull-request@1d3973dc4b8e1399c0620d3f2b1aa5e795465308 # v2.4.3 with: filePath: comment.md comment_tag: preview-docs diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index 2099eb158..7ad73f377 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -11,10 +11,12 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v5 + uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5 + with: + persist-credentials: false - name: Setup Fern CLI - uses: fern-api/setup-fern-cli@v1 + uses: fern-api/setup-fern-cli@d07601425e9c9ede8745d71ca75c4c462d98755d # v1 - name: Publish Docs env: diff --git a/.github/workflows/stale-bot.yml b/.github/workflows/stale-bot.yml index 49974df86..1a92d13ea 100644 --- a/.github/workflows/stale-bot.yml +++ b/.github/workflows/stale-bot.yml @@ -12,7 +12,7 @@ jobs: stale: runs-on: ubuntu-latest steps: - - uses: actions/stale@v10 + - uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f # v10 with: stale-pr-message: 'This PR is stale because it has been open 25 days with no activity. Remove stale label or comment or this will be closed in 5 days.' close-pr-message: 'This PR was closed because it has been inactive for 5 days after being marked stale.' diff --git a/.github/workflows/sync-translations.yml b/.github/workflows/sync-translations.yml new file mode 100644 index 000000000..fab1094f2 --- /dev/null +++ b/.github/workflows/sync-translations.yml @@ -0,0 +1,137 @@ +name: Sync Translations + +on: + # Run nightly at 6 AM UTC + schedule: + - cron: '0 6 * * *' + workflow_dispatch: + +permissions: + contents: write + +jobs: + sync: + name: Update stale translations + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5 + with: + fetch-depth: 0 + persist-credentials: false + + - name: Set up Python + uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 + with: + python-version: '3.12' + + - name: Install dependencies + run: pip install anthropic + + - name: Find and re-translate stale translation files + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + run: | + set -euo pipefail + + # For each zh translation file, check if its EN source has a newer + # commit than the zh file. If so, the translation is stale. + export STALE_EN_FILES="" + for zh_file in $(find fern/translations/zh/products -name '*.mdx' 2>/dev/null); do + en_file="fern/${zh_file#fern/translations/zh/}" + [ -f "$en_file" ] || continue + + en_date=$(git log -1 --format=%ct -- "$en_file" 2>/dev/null || echo 0) + zh_date=$(git log -1 --format=%ct -- "$zh_file" 2>/dev/null || echo 0) + + if [ "$en_date" -gt "$zh_date" ]; then + echo "Stale: $zh_file (EN updated $(date -d @"$en_date" -u +%Y-%m-%d), zh last updated $(date -d @"$zh_date" -u +%Y-%m-%d))" + STALE_EN_FILES="$STALE_EN_FILES $en_file" + fi + done + export STALE_EN_FILES + + if [ -z "$STALE_EN_FILES" ]; then + echo "No stale translation files found" + exit 0 + fi + + python3 << 'PYEOF' + import os, sys, time + import anthropic + + SYSTEM_PROMPT = """You are translating Fern developer documentation from English to Simplified Chinese (zh). + + Rules: + 1. Translate ALL prose, headings, frontmatter (title, description, sidebar-title, headline), callout text, and step titles to Chinese. + 2. DO NOT translate: + - Code blocks (content inside ``` fences) + - Component tag names (, , , , , , , etc.) + - Component prop names and values (e.g. title="...", href="...", src="...", language="...") + - URLs, file paths, import paths + - Variable names, API endpoints, CLI commands, package names + - YAML/JSON keys in code blocks + - includes + - and tags (keep them as-is) + - Content inside blocks (keep in English as it's for AI agents) + 3. Translate component prop values ONLY when they contain human-readable display text: + - Translate: title="Getting started" → title="开始使用" + - Do NOT translate: href="/learn/docs/...", src="./image.png", language="python" + 4. Keep the same MDX structure, whitespace, and formatting as the original. + 5. Keep frontmatter YAML structure exactly the same (same keys, just translate values). + 6. For technical terms commonly kept in English in Chinese tech docs, keep them in English or use the standard Chinese translation with the English term in parentheses on first use. Examples: + - SDK, API, CLI, MDX, YAML, JSON, OpenAPI, gRPC → keep in English + - endpoint → 端点 or keep as endpoint + - middleware → 中间件 + 7. Output ONLY the translated MDX content. No explanations, no markdown fences around the output.""" + + client = anthropic.Anthropic() + stale = os.environ.get("STALE_EN_FILES", "").split() + updated = 0 + + for en_file in stale: + zh_file = "fern/translations/zh/" + en_file.removeprefix("fern/") + with open(en_file) as f: + en_content = f.read() + + print(f"Translating: {en_file} -> {zh_file}") + try: + resp = client.messages.create( + model="claude-sonnet-4-20250514", + max_tokens=16000, + system=SYSTEM_PROMPT, + messages=[{"role": "user", "content": f"Translate this MDX documentation page to Simplified Chinese:\n\n{en_content}"}], + ) + zh_content = resp.content[0].text + + os.makedirs(os.path.dirname(zh_file), exist_ok=True) + with open(zh_file, "w") as f: + f.write(zh_content) + if not zh_content.endswith("\n"): + f.write("\n") + updated += 1 + time.sleep(1) + except Exception as e: + print(f" ERROR translating {en_file}: {e}", file=sys.stderr) + + print(f"Updated {updated}/{len(stale)} translation files") + if updated > 0: + with open(os.environ["GITHUB_ENV"], "a") as f: + f.write("stale_found=true\n") + PYEOF + + - name: Commit and push + if: env.stale_found == 'true' + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + git add fern/translations/zh/ + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git commit -m "chore: re-translate stale zh translations for updated EN pages + + Automatically re-translates zh translation files whose EN source was + updated, keeping pre-computed translations in sync with the latest + English content." + git remote set-url origin "https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }}.git" + git push diff --git a/.github/workflows/update-versions.yml b/.github/workflows/update-versions.yml index 71aaec8a7..07030914a 100644 --- a/.github/workflows/update-versions.yml +++ b/.github/workflows/update-versions.yml @@ -9,9 +9,10 @@ jobs: update-versions: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5 with: ref: main + persist-credentials: false - name: update-csharp-version run: curl -s "https://registry.hub.docker.com/v2/repositories/fernapi/fern-csharp-sdk/tags" | jq -r -j '[.results[] | select(.name != "latest" and .name != "AUTO")] | .[0].name' > fern/snippets/version-number-csharp.mdx - name: update-go-version @@ -36,7 +37,7 @@ jobs: run: curl -s https://api.github.com/repos/fern-api/fern/releases/latest | jq -r -j '.tag_name' > fern/snippets/version-number-cli.mdx - name: create PR id: cpr - uses: peter-evans/create-pull-request@v8 + uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8 with: commit-message: "update versions from docker hub" title: "Update versions from docker hub" @@ -45,7 +46,7 @@ jobs: delete-branch: true - name: Enable Pull Request Automerge if: steps.cpr.outputs.pull-request-operation == 'created' - uses: peter-evans/enable-pull-request-automerge@v3 + uses: peter-evans/enable-pull-request-automerge@a660677d5469627102a1c1e11409dd063606628d # v3 with: pull-request-number: ${{ steps.cpr.outputs.pull-request-number }} merge-method: squash @@ -53,6 +54,7 @@ jobs: if: steps.cpr.outputs.pull-request-operation == 'created' env: GH_TOKEN: ${{ secrets.FERN_GITHUB_TOKEN }} + STEPS_CPR_OUTPUTS_PULL_REQUEST_NUMBER: ${{ steps.cpr.outputs.pull-request-number }} run: | echo "Approving PR" - gh pr review ${{ steps.cpr.outputs.pull-request-number }} --approve + gh pr review ${STEPS_CPR_OUTPUTS_PULL_REQUEST_NUMBER} --approve diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml index c343c4c39..12a375ae7 100644 --- a/.github/workflows/vale.yml +++ b/.github/workflows/vale.yml @@ -15,18 +15,20 @@ jobs: github.event.pull_request.user.login != 'fern-support' && github.event.pull_request.user.login != 'github-actions' steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5 + with: + persist-credentials: false - name: Get changed files id: changed-files - uses: tj-actions/changed-files@v47 + uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6 with: files: | fern/**/*.md fern/**/*.mdx files_ignore: | **/changelog/** - - uses: errata-ai/vale-action@reviewdog + - uses: errata-ai/vale-action@d89dee975228ae261d22c15adcd03578634d429c # v2.1.1 if: steps.changed-files.outputs.any_changed == 'true' with: files: ${{ steps.changed-files.outputs.all_changed_files }} @@ -34,4 +36,4 @@ jobs: reporter: github-pr-review fail_on_error: false env: - GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} \ No newline at end of file + GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} diff --git a/.github/workflows/zizmor.yml b/.github/workflows/zizmor.yml new file mode 100644 index 000000000..3929dd35f --- /dev/null +++ b/.github/workflows/zizmor.yml @@ -0,0 +1,24 @@ +name: GitHub Actions Security Analysis with zizmor + +on: + push: + branches: ["main"] + pull_request: + branches: ["**"] + +permissions: {} + +jobs: + zizmor: + name: Run zizmor + runs-on: ubuntu-latest + permissions: + security-events: write # Required to upload SARIF results to code scanning. + steps: + - name: Checkout repository + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + persist-credentials: false + + - name: Run zizmor + uses: zizmorcore/zizmor-action@b1d7e1fb5de872772f31590499237e7cce841e8e # v0.5.3 diff --git a/.vale/styles/FernStyles/Acronyms.yml b/.vale/styles/FernStyles/Acronyms.yml index 7af037cdc..e444fef52 100644 --- a/.vale/styles/FernStyles/Acronyms.yml +++ b/.vale/styles/FernStyles/Acronyms.yml @@ -108,3 +108,5 @@ exceptions: - SPDX - BCP - ISO + - AUTO + - SHA diff --git a/AGENTS.md b/AGENTS.md index 0e4c68ecf..14f18aab1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,6 +10,15 @@ - Never fabricate information. If you don't know something, say so. - Link between related pages and sections. When you mention a concept that's documented elsewhere, cross-reference it so users can find their way naturally. +## Voice + +Keep prose dry and direct. State requirements and behavior plainly. + +- **Cut hedges and second-person nudges.** "just", "simply", "make sure you", "you'll want to". Prefer "X requires Y" over "make sure you have Y so you can do X". +- **Cut connective filler.** "so that", "in order to", "be sure to" when a flat sentence works. +- **Avoid em dash overuse.** At most one em dash per short paragraph. Before reaching for a second dash, try a colon (for a list or expansion) or parentheses (for an aside). Multiple dashes in close succession read as AI-generated. +- **No conversational framing in callouts and step descriptions.** "Localization requires the latest CLI version" beats "Localization is under active development, so make sure you're on the latest CLI before configuring it." + ## Link checking Internal links between documentation pages use **URL paths built from the YAML config**, not file paths on disk or relative paths. @@ -88,6 +97,87 @@ The correct link is: - **Same-page anchors**: `#section-name` — these don't need a full path. - **Anchors on internal links**: `/learn/docs/config/navigation#section-availability` — append `#anchor` to the URL path. +## Cross-referencing + +When new functionality is documented — whether on a new page or as new behavior added to an existing page — related pages elsewhere in the docs usually need pointers to it. Without those pointers, the canonical content is hard to discover from the angles a reader is most likely to come in from. + +### Pick a canonical home + +One page owns the full explanation; every other page that touches the topic links *to* it rather than restating it. + +- Walkthroughs, setup steps, and concept explanations live on the canonical page. +- Reference pages get a sentence + link, not a paragraph of duplicated detail. +- If you find yourself copying more than a sentence or two into a reference page, the content probably belongs on the canonical page. + +### Find the targets + +Sweep the docs for related touchpoints before assuming you're done: + +```bash +grep -rln "\|" fern/products --include="*.mdx" +``` + +Then read each candidate to find the natural insertion point. Common targets: + +- **Behavior pages** — e.g., a feature affects search → cross-link from `customization/search.mdx`. +- **Dashboard pages** — e.g., a feature has dashboard settings → cross-link from `dashboard/pages/`. +- **Adjacent feature pages** — e.g., Ask Fern, RBAC, localization, when scope or behavior overlaps. +- **Overview / landing pages** — sometimes a card on a hub page is warranted; usually only when the feature is a top-level setup step, not a configuration detail. + +### Pick the form + +| Form | Use when | +|------|----------| +| Inline sentence in an existing paragraph | The reference fits a list of similar items already on the page (e.g., "for sites with X, Y, or [new thing]"). | +| `` callout | The reference is a real but secondary consideration that would distract from the main flow if inlined. | +| New section (`##`) | The target page genuinely needs to document the feature from its own angle (e.g., dashboard config for the feature). | +| New page | Only if the feature has substantial standalone content that doesn't fit elsewhere. | + +Default to the lightest form that works. New pages and new sections add maintenance surface; inline sentences and Notes don't. + +### Phrase inline links naturally + +When the form is inline (the common case), put the link on a natural noun phrase inside the sentence that's already making the point. Don't append a "see [page]" sentence, and don't wrap a one-line pointer in a standalone `` whose only job is to host the link. + +- Good: "Fern emits a set of [analytics events](/learn/docs/integrations/analytics/events) and forwards them to your providers." +- Bad: "Fern emits events. See the [analytics events reference](/learn/docs/integrations/analytics/events) for the list." +- Bad: A standalone `` containing only "For more, see [analytics events reference](/learn/...)." + +Reserve `` and `` callouts for genuinely orthogonal pointers — a tutorial, a related concept that isn't part of the current narrative — not as wrappers for a link that already belongs in the prose. + +### Frame by function, not by plumbing + +Lead the cross-reference with what each feature *does* and how they complement or differ. Don't headline the connection with shared config infrastructure — same YAML key, sibling files in the same directory, same lifecycle. + +- Good: "X decides A; Y decides B." Contrast on function. +- Bad: "Y is also configured under the same `agents` key." Contrast on plumbing. + +If the only thing linking two features is that they live in the same key, that's not a cross-reference worth writing. Config mechanics belong on the page that is itself about configuration. + +### Bidirectional links + +Reference pages always link *to* canonical. Linking back from canonical to a reference page is optional — only do it when the reference page has additional detail the canonical page doesn't cover (e.g., dashboard click-paths). Most cross-references are one-way. + +### Anchor links + +Internal anchors only resolve for `##` / `###` headings. Things that look like headings but aren't: + +- `` inside `` — JSX prop, no anchor generated. +- ``, ``, `` — same. + +If you want to deep-link to a step or tab, add a real `##` heading nearby, or link to the page without an anchor and let the reader scroll. + +### Sweep checklist + +After documenting any new functionality, before declaring the work done: + +1. Grep for the feature/setting name and 1–2 related keywords across `fern/products/**/*.mdx`. +2. For each hit on a different page, decide: is a cross-reference warranted? +3. For each warranted cross-ref, pick the lightest form that fits. +4. Frame each cross-ref by what each feature does, not by shared config keys or directory structure. +5. If the functionality has dashboard settings, verify `fern/products/dashboard/pages/` covers them — usually folded into the most relevant existing page, not a new page. +6. Verify every link you wrote — see *Link checking* above for URL construction. + ## Changelog entries Changelog entries live in `fern/products/docs/pages/changelog/` and `fern/products/dashboard/pages/changelog/`. Filename format: `YYYY-MM-DD.mdx`. diff --git a/fern/docs.yml b/fern/docs.yml index 8f1c5360e..1ad76ba12 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -78,8 +78,6 @@ products: image: ./images/product-switcher/openapi-definition-light.png slug: api-definitions subtitle: Import and configure your API specifications - announcement: - message: 'Fern Definition is no longer actively recommended for new projects but remains supported for existing users.' - display-name: OpenAPI href: /learn/api-definitions/openapi/overview diff --git a/fern/products/api-def/ferndef/api-yml/environments.mdx b/fern/products/api-def/ferndef/api-yml/environments.mdx index 45906c6d0..0d993f383 100644 --- a/fern/products/api-def/ferndef/api-yml/environments.mdx +++ b/fern/products/api-def/ferndef/api-yml/environments.mdx @@ -4,6 +4,8 @@ description: List environments like production, staging, and development. noindex: true --- + + You can specify the environments where your server is deployed. diff --git a/fern/products/api-def/ferndef/api-yml/errors.mdx b/fern/products/api-def/ferndef/api-yml/errors.mdx index 87f76cb9c..7741c1b07 100644 --- a/fern/products/api-def/ferndef/api-yml/errors.mdx +++ b/fern/products/api-def/ferndef/api-yml/errors.mdx @@ -4,6 +4,8 @@ description: Specify error types and schemas noindex: true --- + + In order to generate SDKs idiomatically, Fern needs to know how to differentiate between different errors when parsing an endpoint response. diff --git a/fern/products/api-def/ferndef/api-yml/global-configuration.mdx b/fern/products/api-def/ferndef/api-yml/global-configuration.mdx index 142b5acf7..7d1c1bbef 100644 --- a/fern/products/api-def/ferndef/api-yml/global-configuration.mdx +++ b/fern/products/api-def/ferndef/api-yml/global-configuration.mdx @@ -4,6 +4,8 @@ description: Specify global headers, path parameters or query parameters meant t noindex: true --- + + The `api.yml` configuration supports global configuration like headers and path parameters. diff --git a/fern/products/api-def/ferndef/api-yml/overview.mdx b/fern/products/api-def/ferndef/api-yml/overview.mdx index 5e06a27bd..78ec4e74f 100644 --- a/fern/products/api-def/ferndef/api-yml/overview.mdx +++ b/fern/products/api-def/ferndef/api-yml/overview.mdx @@ -4,6 +4,8 @@ description: The api.yml file contains general API configuration when using the noindex: true --- + + A `fern/` folder has a special file called `api.yml`, which includes all the API-wide configuration. diff --git a/fern/products/api-def/ferndef/audiences.mdx b/fern/products/api-def/ferndef/audiences.mdx index be0bb1b1e..f331ff1f0 100644 --- a/fern/products/api-def/ferndef/audiences.mdx +++ b/fern/products/api-def/ferndef/audiences.mdx @@ -4,6 +4,8 @@ subtitle: Use audiences in your Fern Definition to segment your API for differen noindex: true --- + + diff --git a/fern/products/api-def/ferndef/auth.mdx b/fern/products/api-def/ferndef/auth.mdx index 139484503..5b2eafee4 100644 --- a/fern/products/api-def/ferndef/auth.mdx +++ b/fern/products/api-def/ferndef/auth.mdx @@ -4,6 +4,8 @@ description: Configure API authentication in Fern Definition. Set up bearer toke noindex: true --- + + Configuring authentication schemes happens in the `api.yml` file. All Fern-generated SDKs support both direct configuration and environment variables for authentication credentials. diff --git a/fern/products/api-def/ferndef/availability.mdx b/fern/products/api-def/ferndef/availability.mdx index 66928c91f..35c1256a5 100644 --- a/fern/products/api-def/ferndef/availability.mdx +++ b/fern/products/api-def/ferndef/availability.mdx @@ -4,6 +4,8 @@ description: Add availability to Fern Definition API services, endpoints, types, noindex: true --- + + You can add `availability` to an endpoint, type, or property within your Fern Definition. You can configure the `availability` of sections in your API Reference documentation in your [`docs.yml` file](/learn/docs/configuration/site-level-settings). diff --git a/fern/products/api-def/ferndef/depending-on-other-apis.mdx b/fern/products/api-def/ferndef/depending-on-other-apis.mdx index 03baf715b..cde492345 100644 --- a/fern/products/api-def/ferndef/depending-on-other-apis.mdx +++ b/fern/products/api-def/ferndef/depending-on-other-apis.mdx @@ -4,6 +4,8 @@ subtitle: Import API Definitions to generate unified SDKs noindex: true --- + + Fern allows you to import other APIs into your API. diff --git a/fern/products/api-def/ferndef/endpoints.mdx b/fern/products/api-def/ferndef/endpoints.mdx index e6cc9bd45..b86a6bf88 100644 --- a/fern/products/api-def/ferndef/endpoints.mdx +++ b/fern/products/api-def/ferndef/endpoints.mdx @@ -4,6 +4,8 @@ description: Organize related API endpoints into a service in Fern Definition an noindex: true --- + + In Fern, you organize related endpoints into a **Service**. This grouping improves clarity and makes the generated SDKs more idiomatic. diff --git a/fern/products/api-def/ferndef/endpoints/bytes.mdx b/fern/products/api-def/ferndef/endpoints/bytes.mdx index 3c09c3ca9..09d9d1b4b 100644 --- a/fern/products/api-def/ferndef/endpoints/bytes.mdx +++ b/fern/products/api-def/ferndef/endpoints/bytes.mdx @@ -4,6 +4,8 @@ subtitle: Use the `bytes` type to handle binary data in your API noindex: true --- + + The `bytes` type allows you to handle binary data in both requests and responses. diff --git a/fern/products/api-def/ferndef/endpoints/multipart.mdx b/fern/products/api-def/ferndef/endpoints/multipart.mdx index 0ea3079de..41339bd45 100644 --- a/fern/products/api-def/ferndef/endpoints/multipart.mdx +++ b/fern/products/api-def/ferndef/endpoints/multipart.mdx @@ -4,6 +4,8 @@ description: Document endpoints with the `multiform` content type. noindex: true --- + + Endpoints in Fern are defined underneath the `endpoints` key. If your endpoint request includes file uploads, you can use the `file` type to indicate the request is of a `multiform` content type. The example below demonstrates an endpoint which includes a file in the request body. diff --git a/fern/products/api-def/ferndef/endpoints/rest.mdx b/fern/products/api-def/ferndef/endpoints/rest.mdx index 511cc560e..bf4ab1db3 100644 --- a/fern/products/api-def/ferndef/endpoints/rest.mdx +++ b/fern/products/api-def/ferndef/endpoints/rest.mdx @@ -4,6 +4,8 @@ noindex: true description: "Define HTTP JSON endpoints in the Fern Definition under the endpoints key, including path, method, request bodies, responses, and examples." --- + + Endpoints in Fern are defined underneath the `endpoints` key. Below is an example of defining a single REST endpoint: diff --git a/fern/products/api-def/ferndef/endpoints/sse.mdx b/fern/products/api-def/ferndef/endpoints/sse.mdx index 75e30bf0b..a51d15746 100644 --- a/fern/products/api-def/ferndef/endpoints/sse.mdx +++ b/fern/products/api-def/ferndef/endpoints/sse.mdx @@ -4,6 +4,8 @@ subtitle: Use the `response-stream` key to model streaming endpoints noindex: true --- + + diff --git a/fern/products/api-def/ferndef/errors.mdx b/fern/products/api-def/ferndef/errors.mdx index cf8d2a9d8..a9f11345e 100644 --- a/fern/products/api-def/ferndef/errors.mdx +++ b/fern/products/api-def/ferndef/errors.mdx @@ -4,6 +4,8 @@ description: Add errors representing failed responses from API endpoints in Fern noindex: true --- + + Errors represent failed (non-200) responses from endpoints. diff --git a/fern/products/api-def/ferndef/examples.mdx b/fern/products/api-def/ferndef/examples.mdx index cc581dd58..fe8dca6b7 100644 --- a/fern/products/api-def/ferndef/examples.mdx +++ b/fern/products/api-def/ferndef/examples.mdx @@ -4,6 +4,8 @@ subtitle: Use Fern Definition to add API examples that are shown in comments of noindex: true --- + + You can add examples for types and endpoints. Examples are shown as comments in your SDKs, in the request & response of your documentation, diff --git a/fern/products/api-def/ferndef/export-openapi.mdx b/fern/products/api-def/ferndef/export-openapi.mdx index f60ac136a..8adae6c3d 100644 --- a/fern/products/api-def/ferndef/export-openapi.mdx +++ b/fern/products/api-def/ferndef/export-openapi.mdx @@ -4,6 +4,8 @@ description: Export Fern Definition to OpenAPI 3.1 format using the fern export noindex: true --- + + To prevent lock-in to the Fern Definition format, you can export your API definition to OpenAPI 3.1 at any time [using the `fern export` command](/cli-api-reference/cli-reference/commands#fern-export). diff --git a/fern/products/api-def/ferndef/imports.mdx b/fern/products/api-def/ferndef/imports.mdx index b7a114adf..56792a3df 100644 --- a/fern/products/api-def/ferndef/imports.mdx +++ b/fern/products/api-def/ferndef/imports.mdx @@ -4,6 +4,8 @@ description: Use imports to reference API types and errors from other Fern Defin noindex: true --- + + Imports allow you to reference types and errors from other files. diff --git a/fern/products/api-def/ferndef/overview.mdx b/fern/products/api-def/ferndef/overview.mdx index 15dbbdef9..20c34a5b5 100644 --- a/fern/products/api-def/ferndef/overview.mdx +++ b/fern/products/api-def/ferndef/overview.mdx @@ -4,6 +4,8 @@ description: Fern Definition is a YAML format for API specifications. Define you noindex: true --- + + A Fern Definition is a set of YAML files that are the single source of truth for your API. You check your Fern Definition into your repo, inside of which describes your API requests, responses, models, paths, methods, errors, and authentication scheme. diff --git a/fern/products/api-def/ferndef/packages.mdx b/fern/products/api-def/ferndef/packages.mdx index fd3323875..3eb7dea50 100644 --- a/fern/products/api-def/ferndef/packages.mdx +++ b/fern/products/api-def/ferndef/packages.mdx @@ -4,6 +4,8 @@ description: Fern Definition enables the reuse of API type and error names acros noindex: true --- + + ## What is a package? diff --git a/fern/products/api-def/ferndef/types.mdx b/fern/products/api-def/ferndef/types.mdx index 75ae334c5..c64d060ae 100644 --- a/fern/products/api-def/ferndef/types.mdx +++ b/fern/products/api-def/ferndef/types.mdx @@ -4,6 +4,8 @@ description: Types describe the data model of your API. Fern has many built-in t noindex: true --- + + Types describe the data model of your API. diff --git a/fern/products/api-def/ferndef/webhooks.mdx b/fern/products/api-def/ferndef/webhooks.mdx index c7e9a6502..767737349 100644 --- a/fern/products/api-def/ferndef/webhooks.mdx +++ b/fern/products/api-def/ferndef/webhooks.mdx @@ -5,6 +5,8 @@ max-toc-depth: 3 noindex: true --- + + In Fern, you can specify webhooks in your API definition. The webhooks will be included in both the generated SDKs and the API documentation. diff --git a/fern/products/api-def/ferndef/websockets.mdx b/fern/products/api-def/ferndef/websockets.mdx index fc359b949..65dccff78 100644 --- a/fern/products/api-def/ferndef/websockets.mdx +++ b/fern/products/api-def/ferndef/websockets.mdx @@ -4,6 +4,8 @@ description: Learn how to define WebSockets in the Fern Definition noindex: true --- + + WebSockets enable a user to create a connection with a server, over which bidirectional communication can be sent. diff --git a/fern/products/api-def/openapi/auth.mdx b/fern/products/api-def/openapi/auth.mdx index 7aca361ce..6940b776e 100644 --- a/fern/products/api-def/openapi/auth.mdx +++ b/fern/products/api-def/openapi/auth.mdx @@ -218,6 +218,8 @@ auth-schemes: env: MY_CLIENT_SECRET ``` +[Set `omit: true` on `username` or `password`](/learn/sdks/reference/generators-yml#usernameomit-passwordomit) to remove it from the generated SDK. + diff --git a/fern/products/api-def/openapi/extensions/availability.mdx b/fern/products/api-def/openapi/extensions/availability.mdx index 362281593..b181ca57b 100644 --- a/fern/products/api-def/openapi/extensions/availability.mdx +++ b/fern/products/api-def/openapi/extensions/availability.mdx @@ -5,13 +5,11 @@ description: Mark API endpoint availability in OpenAPI with `x-fern-availability --- -The `x-fern-availability` extension is used to mark the availability of an endpoint within your OpenAPI definition. The availability information propagates into the generated Fern Docs website as visual tags. - -You can configure the `availability` of sections in your API Reference documentation in your [`docs.yml` file](/learn/docs/configuration/site-level-settings). +The `x-fern-availability` extension marks the availability of an endpoint within your OpenAPI definition. The availability information propagates into the generated Fern Docs website as visual tags, SDKs, and [CLIs](/learn/cli-generator/get-started/openapi-extensions#availability-badges). ## Endpoint -The options are: +Set `x-fern-availability` on an endpoint to one of the following values: | Value | Description | Tag | | --- | --- | --- | @@ -31,12 +29,45 @@ paths: x-fern-availability: deprecated ``` -This renders as: +### API Reference output + +The endpoint renders with the corresponding tag in your API Reference docs. ![Screenshot of API Reference endpoint with tag showing deprecated](https://fern-image-hosting.s3.amazonaws.com/fern/x-fern-availability-example.png) +### SDK output + +Availability values propagate into [generated SDKs](/learn/sdks/deep-dives/sdk-user-features#availability) as doc comments on client methods (JSDoc in TypeScript, docstrings in Python, Javadoc in Java, etc.). IDEs surface these as warnings and strikethrough styling so SDK users see at a glance which endpoints to avoid. + +```typescript title="Generated TypeScript SDK" +export class PetClient { + /** @deprecated */ + public addPet( ... ): Promise { ... } + + /** @beta This endpoint is in pre-release and may change. */ + public getPetById( ... ): Promise { ... } +} +``` + + +![Deprecated method with strikethrough and @deprecated tag in VS Code](../../../sdks/images/availability-deprecated-ide.png) + + +To attach a custom message, write `x-fern-availability` as an object with `status` and `message` fields: + +```yaml title="openapi.yml" {4-6} +paths: + /pet: + put: + x-fern-availability: + status: deprecated + message: Use PATCH /pet instead. +``` + + ## Section + diff --git a/fern/products/api-def/openapi/extensions/method-names.mdx b/fern/products/api-def/openapi/extensions/method-names.mdx index c18e0b9a4..82c460fae 100644 --- a/fern/products/api-def/openapi/extensions/method-names.mdx +++ b/fern/products/api-def/openapi/extensions/method-names.mdx @@ -5,7 +5,7 @@ description: Use `x-fern-sdk-method-name` and `x-fern-sdk-group-name` to finetun --- -Use the `x-fern-sdk-group-name` and `x-fern-sdk-method-name` extensions to control how endpoints are organized in your SDK. +Use the `x-fern-sdk-group-name` and `x-fern-sdk-method-name` extensions to control how endpoints are organized in your [SDKs](/learn/sdks/overview/introduction) and [CLIs](/learn/cli-generator/get-started/openapi-extensions). If no extensions are present, Fern uses your operation ID to generate SDK method names. Format operation IDs as `{tag_name}_{operation_name}` (example: `users_get`) to automatically generate methods like `users.get()`. If the operation ID doesn't start with a tag, Fern uses it directly as the method name. diff --git a/fern/products/api-def/openapi/extensions/overview.md b/fern/products/api-def/openapi/extensions/overview.md index f1dc736d3..da37a84fc 100644 --- a/fern/products/api-def/openapi/extensions/overview.md +++ b/fern/products/api-def/openapi/extensions/overview.md @@ -4,7 +4,7 @@ headline: Extensions overview (OpenAPI) description: Learn about OpenAPI extensions in Fern. Customize authentication, SDK methods, versioning, and more for better API specs. --- -Fern supports a variety of OpenAPI extensions that enhance your API specification and generate higher-quality SDKs. +Fern supports a variety of OpenAPI extensions that enhance your API specification and generate higher-quality SDKs and [CLIs](/learn/cli-generator/get-started/openapi-extensions). You can apply these extensions in two ways: by overlaying them in a separate file or by embedding them directly in your OpenAPI specification. See [Overlays](/learn/api-definitions/openapi/overlays) for more information. diff --git a/fern/products/api-def/openapi/extensions/pagination.mdx b/fern/products/api-def/openapi/extensions/pagination.mdx index 8548ecd68..9120fae98 100644 --- a/fern/products/api-def/openapi/extensions/pagination.mdx +++ b/fern/products/api-def/openapi/extensions/pagination.mdx @@ -7,7 +7,7 @@ description: Configure auto-pagination for list endpoints using the x-fern-pagin -The `x-fern-pagination` extension configures auto-pagination for list endpoints in your OpenAPI specification. [Fern's generated SDKs](/learn/sdks/deep-dives/auto-pagination) provide simple iterators that handle pagination automatically, so SDK users can loop through all results without managing pagination complexity manually. +The `x-fern-pagination` extension configures auto-pagination for list endpoints in your OpenAPI specification. [SDK](/learn/sdks/deep-dives/auto-pagination) and [CLI](/learn/cli-generator/get-started/openapi-extensions#pagination) users get automatic pagination without managing page tokens manually. To configure pagination: diff --git a/fern/products/api-def/openapi/overlays.mdx b/fern/products/api-def/openapi/overlays.mdx index 9c72a48dd..61b98ac3e 100644 --- a/fern/products/api-def/openapi/overlays.mdx +++ b/fern/products/api-def/openapi/overlays.mdx @@ -7,7 +7,7 @@ description: Use the OpenAPI Overlay Specification to customize your OpenAPI def Overlays let you customize your OpenAPI specification without modifying the original file. This is useful when: - Your API specification is auto-generated from server code -- You need different configurations for SDKs versus documentation +- You need different configurations for SDKs, documentation, or [generated CLIs](/learn/cli-generator/get-started/customization#overrides-and-overlays) - You want to add Fern configurations like pagination or SDK method names - You want to make bulk changes across many endpoints using JSONPath wildcards diff --git a/fern/products/api-def/pages/overrides.mdx b/fern/products/api-def/pages/overrides.mdx index ca9d24858..710b95072 100644 --- a/fern/products/api-def/pages/overrides.mdx +++ b/fern/products/api-def/pages/overrides.mdx @@ -7,7 +7,7 @@ description: Customize your API definition using a separate overrides file. Use an overrides file to customize your OpenAPI, AsyncAPI, or OpenRPC definition without modifying the original spec. This is useful when: * Your API specification is auto-generated from server code -* You need different configurations for SDKs versus documentation +* You need different configurations for SDKs, documentation, or [generated CLIs](/learn/cli-generator/get-started/customization#overrides-and-overlays) Overrides are available for OpenAPI, AsyncAPI, and OpenRPC specifications. diff --git a/fern/products/api-def/snippets/ferndef-support.mdx b/fern/products/api-def/snippets/ferndef-support.mdx new file mode 100644 index 000000000..feec64b30 --- /dev/null +++ b/fern/products/api-def/snippets/ferndef-support.mdx @@ -0,0 +1,3 @@ + +Fern Definition isn't recommended for new customers and Fern isn't accepting feature requests for this format. It remains supported for existing users. + diff --git a/fern/products/cli-api-reference/cli-changelog/2026-05-10.mdx b/fern/products/cli-api-reference/cli-changelog/2026-05-10.mdx new file mode 100644 index 000000000..d78386222 --- /dev/null +++ b/fern/products/cli-api-reference/cli-changelog/2026-05-10.mdx @@ -0,0 +1,6 @@ +## 5.22.0 +**`(feat):`** Add `fern sdk list` command to list configured and available SDK generators. +Displays configured SDKs from local fern.yml and available generators from the +Fern registry. Supports `--language`, `--type`, and `--json` flags. + + diff --git a/fern/products/cli-api-reference/cli-changelog/2026-05-11.mdx b/fern/products/cli-api-reference/cli-changelog/2026-05-11.mdx new file mode 100644 index 000000000..f0d5cbce8 --- /dev/null +++ b/fern/products/cli-api-reference/cli-changelog/2026-05-11.mdx @@ -0,0 +1,26 @@ +## 5.23.1 +**`(fix):`** Fix `fern docs dev` hanging indefinitely on Node.js v26+ on Linux by disabling +io_uring in the child server process. Node 26 enables io_uring by default in +libuv, which has a busy-loop bug where worker threads spin on an internal +eventfd, starving the main event loop. + + +## 5.23.0 +**`(internal):`** Add an opt-in `VerificationStep` to the post-generation pipeline that runs +`.fern/verify.sh` (when emitted by the generator) inside a language-specific +`{generatorImage}-validator` container after replay and before any GitHub +push. A failing script aborts the pipeline before opening a PR and surfaces +raw stderr through the pipeline logger; a missing script is a silent no-op. + +The step is gated on a hidden `--verify` flag for `fern generate`; when +passed (with `--local` or `--runner`), the local workspace runner sets +`config.verify.enabled = true` on the pipeline and the configured container +runtime (`docker` or `podman`) is forwarded to the validator container. +Remote/Fiddle generation does not honor this flag yet. + + +## 5.22.1 +**`(fix):`** Fix `fern docs dev` failing with pnpm 11 due to esbuild build scripts being blocked by default. +Writes `onlyBuiltDependencies` config to the bundle folder before installing esbuild. + + diff --git a/fern/products/cli-api-reference/cli-changelog/2026-05-12.mdx b/fern/products/cli-api-reference/cli-changelog/2026-05-12.mdx new file mode 100644 index 000000000..b3333e3df --- /dev/null +++ b/fern/products/cli-api-reference/cli-changelog/2026-05-12.mdx @@ -0,0 +1,17 @@ +## 5.23.3 +**`(fix):`** Property-level `x-fern-audiences` filtering now also applies on the V3 OpenAPI / AsyncAPI / +OpenRPC import path used by `fern docs dev` and `fern generate --from-openapi`. Inline +request-body properties, query parameters, inline webhook payload properties, named-type +properties, `v2RequestBodies`, and the docs `v2Examples` blocks (type-level, request body, +response body, endpoint-level, `v2Responses`, and webhook payload examples) are now scrubbed +using the same exclusion semantics as the Fern Definition path. Untagged elements remain +universal and are never silently removed. + + +## 5.23.2 +**`(fix):`** Suppress Fern's platform `User-Agent` header in generated SDKs when the API definition +declares a global `User-Agent` header (case-insensitive) under `api.headers`. This +allows customers to fully override the SDK User-Agent via their Fern Definition without +the auto-generated `/` value also being emitted. + + diff --git a/fern/products/cli-api-reference/cli-changelog/2026-05-13.mdx b/fern/products/cli-api-reference/cli-changelog/2026-05-13.mdx new file mode 100644 index 000000000..f7d2601ea --- /dev/null +++ b/fern/products/cli-api-reference/cli-changelog/2026-05-13.mdx @@ -0,0 +1,30 @@ +## 5.24.0 +**`(internal):`** Plumb `verify`, `verifyRunner`, and `verifyValidatorVersion` flags through +`GenerationRunner.RunArgs` so the seed runner can invoke +`PostGenerationPipeline` with `VerificationStep` and exercise the same +validator-container code path that `fern generate --local --verify` uses. +No customer-facing CLI behavior change — the flags are opt-in and used only +by the seed test runner today. + + +## 5.23.6 +**`(fix):`** Fix `fern docs dev` hot reload not working for .mdx file changes. The backend +now updates the docs definition before notifying the browser to refresh, and +the reload handler properly recovers from errors instead of silently blocking +all future reloads. + + +## 5.23.5 +**`(fix):`** Fix SDK generation crashing with `fatal: is not a valid object` +when the prior fern-bot PR was squash-merged and its branch deleted. +The stale `fern-generation-base` tag update is now skipped with a +warning; the SDK PR still opens. + + +## 5.23.4 +**`(fix):`** Fix allOf composition so inline elements with real constraints (e.g. `pattern`, `minLength`) produce a properly merged type instead of being silently dropped. Also refactored the allOf shortcircuit logic to use a metadata allowlist, which is safer against new OpenAPI fields. + + +**`(fix):`** Fix example generation for allOf compositions to merge base schema fields into property overrides. When an allOf override specifies only `items` without `type: array`, the base schema's type is now correctly inherited, producing properly typed examples instead of null. + + diff --git a/fern/products/cli-api-reference/cli-changelog/2026-05-14.mdx b/fern/products/cli-api-reference/cli-changelog/2026-05-14.mdx new file mode 100644 index 000000000..547149eb0 --- /dev/null +++ b/fern/products/cli-api-reference/cli-changelog/2026-05-14.mdx @@ -0,0 +1,65 @@ +## 5.26.4 +**`(fix):`** Fix `missing-redirects` causing `fern check` to exit with code 1 even when +the rule is configured at `warn`. Rule initialization failures now honor +the configured severity (`warn` emits a warning, `error` emits an error) +instead of always being reported as fatal. The `missing-redirects` rule +also degrades to a warning when the local docs navigation fails to +resolve, captures the underlying `failAndThrow` message so the warning +explains *why* (e.g. `Folder not found: ...`) instead of `[object Object]`, +and non-`Error` throws are formatted readably across the validator. + + +## 5.26.3 +**`(fix):`** Fix `fern docs dev` grabbing the local fern token for authentication when loading a global theme + + +## 5.26.2 +**`(fix):`** Fix commit author attribution for GitHub Enterprise: API-created commits now +use the Fern bot identity instead of the PAT-owning user, matching the git CLI +behavior of Fern 3.x generators. + + +**`(fix):`** Authenticate Venus calls during local Docker generation (`fern generate --local`) +by silently picking up an existing `FERN_TOKEN` env var or saved login token, +matching the remote generation path. Previously, `useLocalDocker` skipped the +auth flow entirely, leaving Venus calls (e.g. `GET /organizations/{org_id}`) +unauthenticated. + + +## 5.26.1 +**`(fix):`** Forward `--verify` through the remote (Fiddle) generation path. Previously the +CLI-level `--verify` flag only worked for local generation; on remote runs the +value was silently dropped before reaching `CreateJobRequestV2.verify`. The +flag now plumbs through `runRemoteGenerationForAPIWorkspace` → +`runRemoteGenerationForGenerator` → `createAndStartJob` and is set on the +Fiddle job request, enabling the generator-cli pipeline's VerificationStep +against the language-specific validator on opted-in runs. + + +## 5.26.0 +**`(feat):`** Add `fern docs link check` command to validate links on live documentation sites. +Supports text, JSON, and CSV output formats via `--output` flag. +Use `--url ` to specify which docs site to check, or auto-detect from docs.yml. + + +**`(feat):`** Add progress bars matching `fern docs dev` style for `fern docs link check`. +Broken links show status codes, blocked links show diagnostic details, +and error messages include actionable context. + + +**`(feat):`** The `fern docs link check` command now resolves broken link sources to local file paths when the server provides `sourcePageIds` and a Fern workspace is available. + + +## 5.25.0 +**`(feat):`** Register the new `fernapi/fern-cli` generator in the CLI configuration. + + +## 5.24.2 +**`(fix):`** Fix `fern config migrate` producing wrong file path references in the generated `fern.yml`. Paths from `generators.yml` (relative to the `fern/` directory) are now correctly re-rooted to be relative to the project root where `fern.yml` is created. This also fixes the `docs` `$ref` pointer to use `./fern/docs.yml` instead of `./docs.yml`. + + +## 5.24.1 +**`(chore):`** Propagate Fern `docs:` strings into generated JSON Schemas so editor hovers +work for schemas served from `schema.buildwithfern.dev`. + + diff --git a/fern/products/cli-api-reference/cli-changelog/2026-05-15.mdx b/fern/products/cli-api-reference/cli-changelog/2026-05-15.mdx new file mode 100644 index 000000000..2f1559951 --- /dev/null +++ b/fern/products/cli-api-reference/cli-changelog/2026-05-15.mdx @@ -0,0 +1,4 @@ +## 5.26.5 +**`(fix):`** Suppress additional Sentry false positives for interrupted syscalls, invalid versions, YAML parse failures, IR schema parse failures, invalid GitHub repository config, replay resolve failures, missing translation directories, and global theme fetch failures. + + diff --git a/fern/products/cli-api-reference/cli-changelog/2026-05-16.mdx b/fern/products/cli-api-reference/cli-changelog/2026-05-16.mdx new file mode 100644 index 000000000..79cf664c8 --- /dev/null +++ b/fern/products/cli-api-reference/cli-changelog/2026-05-16.mdx @@ -0,0 +1,37 @@ +## 5.27.5 +**`(fix):`** Wrap `replaceImagePathsAndUrls` calls in `DocsDefinitionResolver` and `previewDocs` with +try/catch boundaries that convert MDX parse failures to `CliError(ParseError)`, preventing +user-authored MDX syntax errors from reaching Sentry as false-positive InternalErrors. + + +## 5.27.4 +**`(fix):`** Classify service and environment errors at their boundary call sites: mark exhausted +429 retries as NetworkError, pass error objects through failWithoutThrowing in remote +generation so CliError codes propagate, and reclassify docs preview server startup +failures as EnvironmentError instead of InternalError. + + +## 5.27.3 +**`(fix):`** Wrap `yaml.load` calls in `getVersionedNavigationConfiguration` and `getNavigationConfiguration` +with try/catch boundaries that convert YAML parse failures to `CliError(ParseError)`, preventing +user-authored YAML syntax errors in version and product config files from reaching Sentry as +false-positive InternalErrors. + + +## 5.27.2 +**`(fix):`** Suppress Sentry false positives for ENOTEMPTY/ENOMEM syscalls, undici +fetch-failed TypeErrors, and errno codes on error.cause. + + +## 5.27.1 +**`(fix):`** Report escaped fatal CLI errors through telemetry in packaged production runs. + + +## 5.27.0 +**`(internal):`** Enrich CLI telemetry with automation-mode context (config repo, branch, +commit sha, PR number, trigger, and GitHub run details) on every PostHog +event and Sentry error report. +Add the three-leg failure flow (Sentry + PostHog + automation event API) +so automation-run failures surface end-to-end. + + diff --git a/fern/products/cli-api-reference/cli-changelog/2026-05-17.mdx b/fern/products/cli-api-reference/cli-changelog/2026-05-17.mdx new file mode 100644 index 000000000..9b6a2bced --- /dev/null +++ b/fern/products/cli-api-reference/cli-changelog/2026-05-17.mdx @@ -0,0 +1,12 @@ +## 5.27.7 +**`(chore):`** Bump @fern-api/generator-cli to 0.9.30, which includes @fern-api/replay +0.15.2 with a fix for customer commits on merged regen branches surviving +replay detection. + + +## 5.27.6 +**`(chore):`** Bump @fern-api/generator-cli to 0.9.29, which includes @fern-api/replay +0.15.1 with fixes for fallback patch anchoring, composite-patch survival, +and FileOwnership divergence. + + diff --git a/fern/products/cli-api-reference/cli-changelog/2026-05-18.mdx b/fern/products/cli-api-reference/cli-changelog/2026-05-18.mdx new file mode 100644 index 000000000..14c92c99f --- /dev/null +++ b/fern/products/cli-api-reference/cli-changelog/2026-05-18.mdx @@ -0,0 +1,29 @@ +## 5.28.2 +**`(chore):`** Generator-cli now delegates divergent-merge recovery (squash-merge of a regen +PR, force-push past a generation, lost-then-found generations) entirely to +`@fern-api/replay`'s derived scan boundary. Customers no longer hit the +pre-replay precondition gauntlet that occasionally got stuck on stale +`fern-generation-base` tag pointers. Replay still writes the tag for +backward compatibility with older bundled generator-cli versions. + + +## 5.28.1 +**`(fix):`** Fix global theme merge to deep-merge object fields instead of overwriting them. +Local-only sub-fields (e.g. logo.right-text, logo.height) are now preserved +when the global theme defines sibling fields on the same object. + + +## 5.28.0 +**`(feat):`** Consolidate all CLI v2 cache directories into `~/.fern/`. Docs preview bundles are now +managed under `~/.fern/v1/docs-preview/` and discoverable via `fern cache show` and +`fern cache clear --docs-preview`. The `fern cache clear` command never touches the +user's auth token or telemetry ID. + + +## 5.27.8 +**`(fix):`** Fix property-level x-fern-audiences filtering breaking error type resolution when +enableUniqueErrorsPerEndpoint is true. Types referenced via object properties (e.g. +ErrorResponse → ErrorResponseError) are now correctly included during audience filtering, +resolving "Failed to find ErrorResponseError" errors in fern check and fern docs dev. + + diff --git a/fern/products/cli-api-reference/pages/commands.mdx b/fern/products/cli-api-reference/pages/commands.mdx index 642f8251d..b8de8d3ea 100644 --- a/fern/products/cli-api-reference/pages/commands.mdx +++ b/fern/products/cli-api-reference/pages/commands.mdx @@ -29,6 +29,7 @@ hideOnThisPage: true | [`fern docs md check`](#fern-docs-md-check) | Validate MDX syntax in documentation files | | [`fern docs theme export`](#fern-docs-theme-export) | Export theme-eligible fields from `docs.yml` into a standalone directory | | [`fern docs theme upload`](#fern-docs-theme-upload) | Upload a theme to Fern's registry | +| [`fern docs link check`](#fern-docs-link-check) | Check for broken links on a live documentation site | | [`fern docs theme list`](#fern-docs-theme-list) | List all themes for your organization | ## SDK generation commands @@ -276,12 +277,12 @@ hideOnThisPage: true The `--broken-links` and `--strict-broken-links` flags are deprecated. Use the [`broken-links` validation rule](/learn/docs/configuration/site-level-settings#check-configuration) in `docs.yml` instead. - - You can also use the [Fern Dashboard](https://dashboard.buildwithfern.com/) to validate both internal and external links on your live published site. Use `fern check` to validate your API definition and Fern configuration, including [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson), `generators.yml`, and `docs.yml`. It checks for broken links, invalid API examples, configuration errors, and more. When all checks pass, the command produces no output. + Most `fern check` rules — including [`broken-links`](/learn/docs/configuration/site-level-settings#check-configuration) — validate against the navigation tree built from your **local** config and do not crawl your live deployed site or follow external URLs. The exception is the [`missing-redirects` rule](/learn/docs/seo/redirects#catching-missing-redirects), which compares your local navigation against the previously published state and therefore requires `fern login` or `FERN_TOKEN`. + ```bash fern check [--api ] [--warnings] @@ -298,6 +299,10 @@ hideOnThisPage: true missing-redirects: error ``` + + To check links on a published site, use [`fern docs link check`](#fern-docs-link-check) or the link checker in the [Fern Dashboard](https://dashboard.buildwithfern.com/) instead. + + ### api Use `--api ` to specify which API you'd like to check. @@ -464,6 +469,73 @@ hideOnThisPage: true + + + Use `fern docs link check` to scan a live documentation site for broken links. The command crawls the published site, checks every link, and reports broken (404) and blocked (403) URLs along with their source pages. + + + ```bash + fern docs link check [--url ] [--output ] + ``` + + + + Unlike the [`broken-links` rule](#fern-check) in `fern check`, which validates only internal links in your local YAML navigation tree, `fern docs link check` checks all links — internal and external — on your live deployed site. + + + By default, the command auto-detects your docs URL from the `instances` in `docs.yml`. When all links are valid, the command exits with a success message. + + The command first scrapes every page on the site, then checks each link it finds. When broken links are found, the output includes a summary and a grouped list of broken URLs with status codes and source file paths. + + ```plaintext + ◆ Checking links on your-org.docs.buildwithfern.com... + + Scraping pages [████████████████████] 100% | 42/42 + Checking links [████████████████████] 100% | 240/240 + + Finished in 2 minutes, 23 seconds + + Summary + Pages scanned 42 + Links checked 240 + ✓ Working 228 + ✗ Broken 8 (external) + ⚠ Blocked 4 + + ───────────────────────────────────── + + External Broken Links (8) + + ✗ https://example.com/removed-page → 404 + fern/pages/quickstart.mdx + fern/pages/overview.mdx + + ✗ https://example.com/old-endpoint → 404 + fern/pages/integrations.mdx + ``` + + ### url + + Use `--url` to specify which docs site to check. This is useful when you have multiple instances or want to check a preview deployment. + + ```bash + fern docs link check --url https://your-org.docs.buildwithfern.com + ``` + + ### output + + Use `--output` to control the output format. Supported values are `text` (default), `json`, and `csv`. + + ```bash + # JSON output for programmatic use + fern docs link check --output json + + # CSV output for spreadsheets or reporting + fern docs link check --output csv + ``` + + + Use `fern docs md check` to validate MDX syntax across all documentation pages referenced in your navigation configuration, including `docs.yml`, versioned configuration files, and product-specific YAML files. diff --git a/fern/products/cli-generator/authentication.mdx b/fern/products/cli-generator/authentication.mdx new file mode 100644 index 000000000..d0023d808 --- /dev/null +++ b/fern/products/cli-generator/authentication.mdx @@ -0,0 +1,68 @@ +--- +title: Authentication +description: Configure how generated CLIs authenticate with your API using environment variables, CLI flags, files, or fallback chains. +availability: beta +--- + + +The CLI generator is in early access. [Reach out](https://buildwithfern.com/book-demo?type=cli) to get started. + + +Each generated CLI reads authentication credentials from the security schemes declared in your OpenAPI spec. Credentials can come from environment variables, CLI flags, files, or a combination of these through fallback chains. + +Without a credential, the CLI still works — you can explore the command tree, view help, and use `--dry-run`. + +## Credential sources + +The CLI supports several ways to supply credentials, configured at build time. + +| Source | Description | +| --- | --- | +| Environment variable | Read from an env var (the most common option). | +| CLI flag | Auto-registered as a `--` global flag. | +| File | Read trimmed contents from a file path (`~` is expanded). | +| Literal | Baked into the binary at compile time. | +| Fallback chain | Try multiple sources in order; first non-empty value wins. | + +A typical fallback chain lets the CLI flag override the env var, which in turn overrides a file: + +```bash +# CLI flag takes priority +box users get-current-user --api-token sk-123 + +# Otherwise falls back to the environment variable +export BOX_API_KEY=sk-123 +box users get-current-user + +# Otherwise reads from a file +echo "sk-123" > ~/.box/token +box users get-current-user +``` + +## Supported auth schemes + +The CLI supports every scheme type that OpenAPI's `securitySchemes` defines: + +| Scheme | How the CLI applies it | +| --- | --- | +| Bearer (`http: bearer`) | Sends `Authorization: Bearer `. | +| API key (`apiKey`) | Sends the key in the configured header (for example, `X-Auth-Token`). | +| Basic (`http: basic`) | Sends `Authorization: Basic `. Each field has its own credential source. | +| OAuth 2 | Treated as bearer — sends `Authorization: Bearer `. | + +## Auth strategies + +When a spec declares multiple security schemes, the CLI composes them according to one of these strategies: + +| Strategy | Behavior | +| --- | --- | +| Auto | Default. Infers the right composition from the spec's `security` blocks. | +| Any | The API accepts any one of the declared schemes. The first scheme with a credential wins. | +| All | The API requires every scheme simultaneously (for example, HMAC signature plus API key). | +| Routing | Per-operation dispatch. Each endpoint's `security` block determines which schemes to use. | + +Operations that declare `security: []` (an empty list) opt out of authentication entirely — no credentials are sent regardless of what's configured. + +## Help output + +Every generated CLI includes a dynamically rendered `Authentication:` section in its `--help` output listing every scheme, the expected env var or flag, and whether a credential is detected. diff --git a/fern/products/cli-generator/cli-generator.yml b/fern/products/cli-generator/cli-generator.yml index 7519597cd..78c95aaeb 100644 --- a/fern/products/cli-generator/cli-generator.yml +++ b/fern/products/cli-generator/cli-generator.yml @@ -4,4 +4,15 @@ navigation: - page: Overview path: ./overview.mdx slug: overview - + - page: Features + path: ./features.mdx + slug: features + - page: Authentication + path: ./authentication.mdx + slug: authentication + - page: OpenAPI extensions + path: ./openapi-extensions.mdx + slug: openapi-extensions + - page: Customization + path: ./customization.mdx + slug: customization diff --git a/fern/products/cli-generator/customization.mdx b/fern/products/cli-generator/customization.mdx new file mode 100644 index 000000000..edc0020b2 --- /dev/null +++ b/fern/products/cli-generator/customization.mdx @@ -0,0 +1,68 @@ +--- +title: Customization +description: Customize generated CLIs with overrides, overlays, multi-spec merging, and custom commands. +availability: beta +--- + + +The CLI generator is in early access. [Reach out](https://buildwithfern.com/book-demo?type=cli) to get started. + + +A generated CLI can be customized at three levels: the OpenAPI spec it's built from, the configuration that combines multiple specs into a single command tree, and code that adds custom commands alongside the spec-derived ones. + +## Overrides and overlays + +The CLI generator supports both [overrides](/learn/api-definitions/openapi/overrides) and [overlays](/learn/api-definitions/openapi/overlays) for customizing the OpenAPI spec before the CLI is built. This lets you add Fern extensions, rename parameters, or remove internal endpoints without modifying your original spec. + +Overlays follow the [OpenAPI Overlay Specification](https://spec.openapis.org/overlay/v1.0.0.html) and use JSONPath to target elements: + +```yaml title="overlay.yaml" +overlay: 1.0.0 +info: + title: CLI customizations + version: 1.0.0 +actions: + - target: $.paths['/plants'].get + update: + x-fern-sdk-group-name: plants + x-fern-sdk-method-name: list + - target: $.paths['/internal/debug'] + remove: true +``` + +When both are present, overrides are applied first, then overlays. + +## Multi-spec merging + +A single CLI can combine multiple OpenAPI specs into one command tree. This is useful for APIs that split their spec across domains or versions. + +Specs can be merged flat (all commands at the top level) or under a namespace prefix: + +```rust title="main.rs" +CliApp::new("my-api") + .spec(include_str!("core.yaml")) + .spec_under("billing", include_str!("billing.yaml")) + .run() +``` + +This produces a CLI where core commands live at the top level and billing commands live under a `billing` subcommand: + +```bash +my-api users list # from core.yaml +my-api billing invoices list # from billing.yaml +``` + +When a namespace matches a top-level resource in the incoming spec, the CLI hoists that resource's methods into the namespace to avoid repetition (for example, `billing billing invoices list` becomes `billing invoices list`). + +## Custom commands + +Generated CLIs can include custom commands alongside the spec-derived ones. Custom commands have access to the same API executor, so they can chain multiple API calls into a single workflow. + +```rust title="main.rs" +CliApp::new("my-api") + .spec(include_str!("openapi.yaml")) + .auth_scheme_env("bearerAuth", "MY_API_TOKEN") + .command(whoami_cmd(), whoami_handler) + .run() +``` + diff --git a/fern/products/cli-generator/features.mdx b/fern/products/cli-generator/features.mdx new file mode 100644 index 000000000..f7d770175 --- /dev/null +++ b/fern/products/cli-generator/features.mdx @@ -0,0 +1,146 @@ +--- +title: Features +description: Explore the capabilities of Fern's generated CLIs, including output formatting, pagination, dry-run mode, and TLS configuration. +availability: beta +--- + + +The CLI generator is in early access. [Reach out](https://buildwithfern.com/book-demo?type=cli) to get started. + + +Generated CLIs ship with a common set of runtime flags and environment variables: output formatting, pagination, dry-run previewing, TLS and proxy configuration, exit codes, and structured logging. APIs with templated server URLs also expose per-variable flags and environment variables. + +## Output formatting + +Use the `--format` flag to control how responses are displayed. + +| Format | Flag | Description | +| --- | --- | --- | +| JSON | `--format json` | Default. Pretty-printed JSON. | +| Table | `--format table` | Columnar table. Nested objects flatten to `parent.child` column names. | +| YAML | `--format yaml` | YAML representation of the response. | +| CSV | `--format csv` | Comma-separated values, suitable for piping into spreadsheet tools. | + +```bash +# Display plants in a table +contoso plants list --format table + +# Export orders as CSV +contoso orders list --format csv > orders.csv +``` + +## Dry-run mode + +Pass `--dry-run` to validate arguments and preview the HTTP request without sending it. The CLI prints the method, URL, headers, and body it would send, then exits. + +```bash +contoso plants get --params '{"plantId": "abc"}' --dry-run +``` + +## Pagination + +For endpoints annotated with [`x-fern-pagination`](/learn/api-definitions/openapi/extensions/pagination), the CLI auto-paginates when the `--page-all` flag is set. + +| Flag | Description | Default | +| --- | --- | --- | +| `--page-all` | Fetch every page and emit one JSON line per page (NDJSON). | Off | +| `--page-limit ` | Maximum number of pages to fetch. | 10 | +| `--page-delay ` | Delay in milliseconds between page requests. | 100 | + +```bash +# Fetch all plants, one JSON line per page +contoso plants list --page-all + +# Limit to 5 pages with a 200 ms delay +contoso plants list --page-all --page-limit 5 --page-delay 200 +``` + +Paginated output works with all output formats. For table and CSV formats, headers are only emitted on the first page so the output concatenates cleanly. + +## Passing parameters + +| Flag | Purpose | +| --- | --- | +| `--params ` | URL path and query parameters as a JSON object. | +| `--json ` | Request body for POST, PUT, and PATCH methods. | + +```bash +# Path + query parameters +contoso plants get --params '{"plantId": "abc"}' + +# Request body +contoso plants create \ + --json '{"name": "Monstera", "species": "Monstera deliciosa", "sunlight": "indirect"}' +``` + +## Server URL variables + +For APIs with [templated server URLs](/learn/api-definitions/openapi/extensions/server-names-and-url-templating) (such as `https://api.example.com/stores/{store_hash}/v3`), the CLI automatically exposes each template variable as a CLI flag and environment variable. + +```bash +# Pass the variable as a flag +bigcommerce --store-hash abc123 v3 customers list + +# Or set it via an environment variable +export BIGCOMMERCE_STORE_HASH=abc123 +bigcommerce v3 customers list +``` + +## File uploads and downloads + +For endpoints with `format: binary` request bodies, pass a file path as the `--file` argument. For binary responses, use `--output ` to save the response body to a file. + +## Exit codes + +| Code | Meaning | Example cause | +| --- | --- | --- | +| `0` | Success | Command completed normally. | +| `1` | API error | Server returned a 4xx/5xx response. | +| `2` | Auth error | Credentials missing or invalid. | +| `3` | Validation error | Bad arguments, unknown command, or invalid JSON. | +| `4` | Discovery error | Couldn't load API schema. | +| `5` | Internal error | Unexpected failure. | + +All errors are emitted as structured JSON on stderr, making them easy to parse in scripts and CI pipelines. + +## TLS, proxies, and CA bundles + +Every generated CLI honors environment variables for TLS and proxy configuration at runtime. Variables are scoped by binary name — `` is the CLI's binary name uppercased with hyphens mapped to underscores (for example, `CONTOSO`). + +| Variable | Effect | +| --- | --- | +| `_CA_BUNDLE` | Path to a PEM file appended to the default trust roots. | +| `_INSECURE=1` | Disable TLS verification. Logs a warning. Not for production use. | +| `_PROXY` | HTTP/HTTPS proxy URL, overriding `HTTPS_PROXY` / `HTTP_PROXY`. | +| `_NO_PROXY` | Comma-separated proxy bypass list scoped to this CLI. | +| `_TIMEOUT_SECS` | Total request timeout. None by default. | +| `_CONNECT_TIMEOUT_SECS` | Connection-establishment timeout. | + +Standard environment variables (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, `SSL_CERT_FILE`) are honored when the scoped overrides are absent. + + + +**Behind a MITM proxy (Proxyman, Charles, mitmproxy):** + +```bash +export SSL_CERT_FILE=~/path/to/proxyman-ca.pem +export HTTPS_PROXY=http://127.0.0.1:9090 +contoso plants list +``` + +**Corporate network with a custom root CA:** + +```bash +export CONTOSO_CA_BUNDLE=/etc/ssl/corp-roots.pem +contoso plants list +``` + + + +## Structured logging + +Logging is off by default. Set `_LOG` to a [tracing filter](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html) to emit structured logs to stderr. Set `_LOG_FILE` to a directory path to write daily rotated JSON log files. + +```bash +CONTOSO_LOG=debug contoso plants list +``` diff --git a/fern/products/cli-generator/openapi-extensions.mdx b/fern/products/cli-generator/openapi-extensions.mdx new file mode 100644 index 000000000..01b516cc4 --- /dev/null +++ b/fern/products/cli-generator/openapi-extensions.mdx @@ -0,0 +1,144 @@ +--- +title: OpenAPI extensions +description: Learn which Fern OpenAPI extensions influence the generated CLI and how they map to commands, flags, and help text. +availability: beta +--- + + +The CLI generator is in early access. [Reach out](https://buildwithfern.com/book-demo?type=cli) to get started. + + +The CLI generator reads several [Fern OpenAPI extensions](/learn/api-definitions/openapi/extensions/overview) to shape the generated CLI. You can add these extensions directly in your spec or apply them through [overlays](/learn/api-definitions/openapi/overlays). + +## Command structure + +### `x-fern-sdk-group-name` + +Determines the subcommand group hierarchy. Each list element becomes a nested subcommand, with names converted from camelCase to kebab-case. + +```yaml title="openapi.yaml" {4-6} +paths: + /scheduled-events/{uuid}/invitees: + get: + x-fern-sdk-group-name: + - scheduledEvents + - invitees + x-fern-sdk-method-name: list-event-invitees +``` + +Produces: `cli scheduled-events invitees list-event-invitees` + +### `x-fern-sdk-method-name` + +Sets the leaf command name (used as-is). + +```yaml title="openapi.yaml" {4} +paths: + /users/me: + get: + x-fern-sdk-method-name: get-current-user +``` + +Produces: `cli get-current-user` (or nested under a group if `x-fern-sdk-group-name` is also set). + + +If neither extension is present, the CLI falls back to the `operationId`. + + +See [SDK method names](/learn/api-definitions/openapi/extensions/method-names) for more details. + +## Filtering + +### `x-fern-ignore` + +Excludes operations or parameters from the generated CLI. An ignored operation produces no command; an ignored parameter produces no flag. + +```yaml title="openapi.yaml" {4} +paths: + /internal/debug: + get: + x-fern-ignore: true +``` + +At the parameter level: + +```yaml title="openapi.yaml" {7} +paths: + /users: + get: + parameters: + - name: internalParam + in: query + x-fern-ignore: true + schema: + type: string +``` + +See [Ignoring elements](/learn/api-definitions/openapi/extensions/ignoring-elements) for more details. + +## Availability badges + +### `x-fern-availability` + +Adds a status badge next to the command in `--help` output. + +| Value | Badge | +| --- | --- | +| `alpha` | `[Alpha]` | +| `beta` | `[Beta]` | +| `preview` | `[Preview]` | +| `generally-available` or `ga` | `[GA]` | +| `deprecated` | `[Deprecated]` | +| `legacy` | `[Legacy]` | + +```yaml title="openapi.yaml" {4} +paths: + /v2/reports: + get: + x-fern-availability: beta +``` + +OpenAPI's standard `deprecated: true` is also honored and maps to `[Deprecated]` when `x-fern-availability` isn't set. + +See [Availability](/learn/api-definitions/openapi/extensions/availability) for more details. + +## Parameter naming + +### `x-fern-parameter-name` + +Overrides the CLI flag name derived from a parameter. By default, parameter names are converted to kebab-case for use as flags. + +```yaml title="openapi.yaml" {9} +paths: + /users: + get: + parameters: + - name: X-API-Version + in: header + schema: + type: string + x-fern-parameter-name: api-version +``` + +Produces `--api-version` instead of `--x-api-version`. + +See [Customize parameter names](/learn/api-definitions/openapi/extensions/parameter-names) for more details. + +## Pagination + +### `x-fern-pagination` + +Enables auto-pagination for an endpoint. When present, the CLI recognizes `--page-all`, `--page-limit`, and `--page-delay` flags for that command. + +```yaml title="openapi.yaml" {5-8} +paths: + /plants: + get: + operationId: list_plants + x-fern-pagination: + cursor: $request.cursor + next_cursor: $response.next + results: $response.results +``` + +See [Pagination](/learn/api-definitions/openapi/extensions/pagination) for all supported pagination schemes (offset, cursor, URI, and path). diff --git a/fern/products/cli-generator/overview.mdx b/fern/products/cli-generator/overview.mdx index c78e4ede6..763595728 100644 --- a/fern/products/cli-generator/overview.mdx +++ b/fern/products/cli-generator/overview.mdx @@ -25,6 +25,10 @@ Building a CLI by hand is a multi-quarter project — commands, auth, pagination ## How it works + +Generate a CLI from an OpenAPI spec or a GraphQL introspection schema. + + The CLI generator plugs into the same Fern workflow as your Docs and SDKs. When your spec changes, Fern opens a PR against your CLI repo with the generated source. On release, Fern automatically publishes the CLI to npm, Homebrew, and GitHub Releases so your users can install it with their package manager of choice. The CLI stays in sync with your Docs and SDKs, and you never need to write CLI code by hand. The output is a single statically linked Rust binary. Users drop it onto their PATH and run it. There's no language runtime and no dependencies. diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index 77e194548..41cd6ddac 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -409,24 +409,27 @@ navigation: contents: - page: Overview path: ./pages/integrations/overview.mdx - - page: Intercom - path: ./pages/integrations/support/intercom.mdx - slug: support/intercom - - page: Google - path: ./pages/integrations/analytics/google.mdx - slug: analytics/google - page: PostHog path: ./pages/integrations/analytics/posthog.mdx slug: analytics/posthog - - page: Fullstory - path: ./pages/integrations/analytics/fullstory.mdx - slug: analytics/fullstory + - page: Google + path: ./pages/integrations/analytics/google.mdx + slug: analytics/google - page: Segment path: ./pages/integrations/analytics/segment.mdx slug: analytics/segment - page: Mixpanel path: ./pages/integrations/analytics/mixpanel.mdx slug: analytics/mixpanel + - page: Analytics events reference + path: ./pages/integrations/analytics/analytics-events.mdx + slug: analytics/events + - page: Fullstory + path: ./pages/integrations/analytics/fullstory.mdx + slug: analytics/fullstory + - page: Intercom + path: ./pages/integrations/support/intercom.mdx + slug: support/intercom - page: Postman path: ./pages/integrations/postman.mdx - page: Context7 @@ -509,6 +512,8 @@ navigation: hidden: true - website: hidden: true + - scribeWebhooks: + hidden: true # must be included to use the schema component - api: API reference api-name: docs-yml diff --git a/fern/products/docs/pages/ai/fern-writer.mp4 b/fern/products/docs/pages/ai/fern-writer.mp4 index cbc7afc6c..7db9f3f71 100644 Binary files a/fern/products/docs/pages/ai/fern-writer.mp4 and b/fern/products/docs/pages/ai/fern-writer.mp4 differ diff --git a/fern/products/docs/pages/ai/writer-open-pr.png b/fern/products/docs/pages/ai/writer-open-pr.png index d44644ea1..a1b94c265 100644 Binary files a/fern/products/docs/pages/ai/writer-open-pr.png and b/fern/products/docs/pages/ai/writer-open-pr.png differ diff --git a/fern/products/docs/pages/ai/writer-slack.png b/fern/products/docs/pages/ai/writer-slack.png deleted file mode 100644 index f56b83f31..000000000 Binary files a/fern/products/docs/pages/ai/writer-slack.png and /dev/null differ diff --git a/fern/products/docs/pages/ai/writer.mdx b/fern/products/docs/pages/ai/writer.mdx index 07f8595ca..79c4ce423 100644 --- a/fern/products/docs/pages/ai/writer.mdx +++ b/fern/products/docs/pages/ai/writer.mdx @@ -6,11 +6,15 @@ description: A Slack-based technical writing agent that updates your documentati Fern Writer is a Slack-based technical writing agent that keeps your docs aligned as your product evolves. It's powered by [Devin from Cognition](https://cognition.ai/blog/introducing-devin). Fern Writer understands Fern components and your writing style, and can be customized via an `AGENTS.md` file in your docs repository. - - Fern Writer in Slack + + ## How it works @@ -19,34 +23,8 @@ Fern Writer is a Slack-based technical writing agent that keeps your docs aligne In Slack channels where you've added Fern Writer, tag `@Fern Writer` and describe the change you need. Fern Writer [only responds when directly tagged](#privacy-and-data-handling). It will react to your message to confirm receipt, then create a pull request and reply with a link. - - Fern Writer opening a PR - - Fern Writer supports image and file attachments for additional context. When tagged in an existing thread, it reads the full conversation to understand context before responding. -| Use case | Sample request | -|----------|----------------| -| Document a new feature from a pull request | `@Fern Writer document the new rate limiting feature added in PR #123` | -| Add new content to existing pages | `@Fern Writer add a section about webhook retry behavior to the webhooks guide` | -| Reorganize and consolidate content | `@Fern Writer merge the authentication and authorization pages, and add a redirect from the old auth page` | -| Fix errors and improve clarity | `@Fern Writer fix the broken code example in the quickstart and update the package version to v2.1.0` | - - - - - ### Reviewing and merging Request changes by commenting in the Slack thread. Once the PR meets your requirements, merge it like any other pull request. @@ -62,6 +40,30 @@ Request changes by commenting in the Slack thread. Once the PR meets your requir Each pull request includes a **Requested by** field in the description, attributing the change to the person or team that initiated the request. Commits are signed and attributed to `fern-support`, ensuring that automated changes are clearly distinguishable from manual contributions in your repository's history. +## Example requests + + +@Fern Writer document the new rate limiting feature added in PR #123 + + +
+ + +@Fern Writer add a section about webhook retry behavior to the webhooks guide + + +
+ + +@Fern Writer merge the authentication and authorization pages, and add a redirect from the old auth page + + +
+ + +@Fern Writer fix the broken code example in the quickstart and update the package version to v2.1.0 + + ## Setup diff --git a/fern/products/docs/pages/api-references/library-docs.mdx b/fern/products/docs/pages/api-references/library-docs.mdx index e00a59ce9..5396750d7 100644 --- a/fern/products/docs/pages/api-references/library-docs.mdx +++ b/fern/products/docs/pages/api-references/library-docs.mdx @@ -4,7 +4,9 @@ description: Generate MDX documentation pages from your Python or C++ library so --- -The library docs generator parses your **Python or C++** library source code and generates MDX documentation pages for modules, classes, functions, methods, and parameters. Generated pages include cross-reference links and hierarchical navigation, and are integrated directly into your Fern Docs site. +The library docs generator parses your **Python or C++** library source code and generates MDX documentation pages for modules, classes, functions, methods, and parameters. Generated pages are added to your Fern Docs site with hierarchical navigation. + +Cross-links are automatic. When a fully-qualified identifier appears in a code block — for example, in a class signature or type annotation — the generator links it to the page documenting that symbol, so readers can jump straight to the definition. ## Configuration diff --git a/fern/products/docs/pages/changelog/2026-05-14.mdx b/fern/products/docs/pages/changelog/2026-05-14.mdx new file mode 100644 index 000000000..65c76969c --- /dev/null +++ b/fern/products/docs/pages/changelog/2026-05-14.mdx @@ -0,0 +1,16 @@ +--- +tags: ["configuration"] +--- + +## CLI link checker + +You can now check for broken links on your live documentation site directly from the Fern CLI with `fern docs link check`. The command scrapes every page on your published site, checks all internal and external links, and reports broken (404) and blocked (403) URLs along with the source pages where they appear. + +```bash +fern docs link check --url https://buildwithfern.com/learn +fern docs link check --url https://elevenlabs.io/docs +``` + +This complements the existing [`broken-links` rule](/learn/docs/configuration/site-level-settings#check-configuration) in `fern check`, which validates internal links against your local YAML navigation tree. Use `fern docs link check` after publishing to catch live 404s and broken external URLs that local validation can't detect. + + diff --git a/fern/products/docs/pages/component-library/default-components/runnable-endpoint.mdx b/fern/products/docs/pages/component-library/default-components/runnable-endpoint.mdx index 57f7540ab..f3d4e5efc 100644 --- a/fern/products/docs/pages/component-library/default-components/runnable-endpoint.mdx +++ b/fern/products/docs/pages/component-library/default-components/runnable-endpoint.mdx @@ -4,26 +4,31 @@ description: Add testable API endpoints to your docs with RunnableEndpoint. Supp --- -The `` component lets users make real HTTP requests to your APIs directly in the API Reference. It auto-detects endpoint definitions from your API specification and provides a request builder with inputs for headers, path parameters, query parameters, and request bodies. +The `` component lets users make real HTTP requests to your APIs directly from your documentation. It auto-detects the endpoint definition from your API specification, renders a request builder for headers, path parameters, query parameters, and request bodies, and displays the response status, headers, body, and timing inline. Form inputs persist in local storage across page reloads. ## Usage
- ![Runnable Endpoint component example](runnable-endpoint.png) +
```jsx Markdown - + ``` -## Features +## Variants -The component supports: -- **Multiple examples** – When your endpoint has multiple pre-configured examples, the component displays a dropdown selector in the header so users can switch between different examples -- **Multiple environments** – If your API defines multiple environments (production, staging, development), the component automatically displays an environment selector so users can test against different base URLs -- **API Reference integration** – Each `` includes a button that links users to the full API Reference documentation for the endpoint -- **Real-time response preview** – Users can view response status, headers, body, and response time immediately after sending requests -- **Form persistence** – Form inputs are automatically persisted in the browser's local storage, so users' test data is preserved even when navigating between pages or refreshing the browser +### Collapse by default + +Use `collapsed` to render the component with the form section hidden. Users can expand it by clicking the component. + +
+ +
+ +```jsx Markdown + +``` ## Properties diff --git a/fern/products/docs/pages/component-library/default-components/webhook-payload-snippet.mdx b/fern/products/docs/pages/component-library/default-components/webhook-payload-snippet.mdx index ad8f9004c..a197f2546 100644 --- a/fern/products/docs/pages/component-library/default-components/webhook-payload-snippet.mdx +++ b/fern/products/docs/pages/component-library/default-components/webhook-payload-snippet.mdx @@ -4,16 +4,26 @@ description: Reference a webhook payload from your API Reference to display exam --- -Use the `` component to reference a webhook payload from your API Reference. +The `` component displays a webhook's request payload schema from your API Reference. It renders the same fields, types, and example values that appear on the webhook's full API Reference page, so readers can inspect the payload inline alongside your prose. + +To display the schema for a regular HTTP endpoint, use the [``](/learn/docs/writing-content/components/endpoint-schema-snippet) component. ## Usage +Reference a webhook by its `operationId`. + +
+
+ +
+
+ ```jsx Markdown - + ``` ## Properties - The operation ID of the webhook to display. + The `operationId` of the webhook to display. If your API uses [namespaces](/learn/api-definitions/overview/project-structure#combined-sdks-from-multiple-apis), prefix with the namespace and `::` (e.g., `payments::on-payment-succeeded`). diff --git a/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx b/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx index bd867092d..287cd765d 100644 --- a/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx +++ b/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx @@ -55,14 +55,34 @@ Because the `

` is generated automatically, you should begin your page conten ## Links in Markdown ### Link format -Use a `/` character to begin a relative URL to another page on your docs site. This routes to the `url` defined in your `docs.yml` file, such as `example-docs.buildwithfern.com`. For example, if you want to link to `https://example-docs.buildwithfern.com/overview/introduction`, you can write the link in Markdown as follows: - -```mdx -Read the [Introduction](/learn/sdks/overview/introduction). +To link to another page on your docs site, write the destination's **published site path**, starting with a `/`. Fern builds this path from the slugs in your [`docs.yml` and product YAML files](/learn/docs/configuration/navigation), not from the file's location on disk. To link to a heading on another page, append `#anchor` to the path. + + + File-relative paths like `./` and `../` aren't supported for inter-page links — use the published site path instead. (File-relative paths are still correct for [images and other media](/learn/docs/writing-content/markdown-media) and for `path:` references inside YAML config.) + + + +```mdx wordWrap +Learn about [how Fern SDKs work](/learn/sdks/overview/how-it-works). + +Configure [sidebar icons](/learn/docs/configuration/navigation#sidebar-icons) to add visual cues to your navigation. ``` +In [versioned docs](/learn/docs/configuration/versions), the same path lands on a different version depending on whether you write the unversioned form (default version) or the versioned form (e.g. `/learn/docs/v2/getting-started`). For inline version-specific content within a single page, use [``](/learn/docs/writing-content/components/if#by-version) or [``](/learn/docs/writing-content/components/versions). + +### Validating links + +Fern provides two ways to catch broken links. The [`broken-links` rule](/learn/docs/configuration/site-level-settings#check-configuration) — run by [`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check), including during `fern docs dev` — validates each internal link against the navigation tree built from your **local** YAML. To check links on a published site, use [`fern docs link check`](/learn/cli-api-reference/cli-reference/commands#fern-docs-link-check) or the [Fern Dashboard](https://dashboard.buildwithfern.com/). + +| | `fern check` broken-links rule | `fern docs link check` | +|---|---|---| +| What it checks | Internal links in your **local** YAML navigation tree | All links on your **live deployed** site | +| External links | Not checked | Checked | +| Requires a published site | No | Yes | +| When to use | In CI, before publishing | After publishing, to catch live 404s and broken external URLs | + ### API link syntax diff --git a/fern/products/docs/pages/getting-started/quickstart.mdx b/fern/products/docs/pages/getting-started/quickstart.mdx index e561f6669..bfb06c9b6 100644 --- a/fern/products/docs/pages/getting-started/quickstart.mdx +++ b/fern/products/docs/pages/getting-started/quickstart.mdx @@ -37,7 +37,7 @@ This guide covers the CLI path. A browser-based guided setup also exists at http - All the configuration for your docs lives in the `fern` folder. Create a fern folder by either using the [starter template](https://github.com/fern-api/docs-starter) or starting from scratch + All the configuration for your docs lives in the `fern` folder. Create a fern folder by either using the [starter template](https://github.com/fern-api/docs-starter) or starting from scratch. Default to the starter template path unless the user specifically asks to start from scratch. The template includes sample pages, an OpenAPI spec, a changelog, and a GitHub Actions workflow — it's much faster to delete what you don't need than to build from nothing. @@ -147,7 +147,7 @@ This guide covers the CLI path. A browser-based guided setup also exists at http - Now that you have a basic docs site, you can customize it by adding tutorials, generating an API Reference, or finetuning the branding. (Or skip ahead to [preview](#preview-your-docs) and [publish](#publish-to-production).) + Now that you have a basic docs site, you can customize it by adding tutorials, generating an API Reference, or fine-tuning the branding. (Or skip ahead to [preview](#preview-your-docs) and [publish](#publish-to-production).) diff --git a/fern/products/docs/pages/integrations/analytics/analytics-events.mdx b/fern/products/docs/pages/integrations/analytics/analytics-events.mdx new file mode 100644 index 000000000..eeec0d95d --- /dev/null +++ b/fern/products/docs/pages/integrations/analytics/analytics-events.mdx @@ -0,0 +1,61 @@ +--- +title: Analytics events reference +description: Complete reference of the analytics events Fern emits on your documentation site, including page views, feedback, API Playground, search, and error tracking events. +--- + +This page lists every analytics event Fern emits from your documentation site. The **Forwarded to** column in each table shows which [configured providers](/learn/docs/integrations/overview) receive that event — not every provider receives every event. + + +[FullStory](/learn/docs/integrations/analytics/fullstory) and [Intercom](/learn/docs/integrations/support/intercom) provide session recording and live chat respectively. They don't receive the named events listed below. + + +## Page views + +| Event | Description | Forwarded to | +| --- | --- | --- | +| `$pageview` | Fired on every route change. Includes the current URL. | PostHog, Segment | +| `$pageleave` | Fired when a user navigates away from a page. | PostHog | + +Page view tracking is automatic and requires no additional configuration. GA4 and Google Tag Manager (GTM) handle their own page view tracking natively when configured. + +## Feedback events + +These events are emitted by the [on-page feedback](/learn/docs/user-feedback) widget and the Ask Fern feedback component. + +| Event | Description | Forwarded to | +| --- | --- | --- | +| `feedback_voted` | User clicked the thumbs up or thumbs down button. | PostHog, GA4, GTM | +| `feedback_submitted` | User submitted written feedback after voting. | PostHog, GA4, GTM | +| `code_block_feedback_opened` | User opened the feedback prompt on a code block. | PostHog, GA4, GTM | +| `code_block_feedback_submitted` | User submitted feedback on a code block. | PostHog, GA4, GTM | + +## API playground events + +These events track usage of the [API Explorer](/learn/docs/api-references/api-explorer). + +| Event | Description | Forwarded to | +| --- | --- | --- | +| `api_playground_request_sent` | User sent a request from the API Explorer. | PostHog, GA4, GTM | +| `api_playground_request_received` | A response was received in the API Explorer. | PostHog, GA4, GTM | + +## Search and AI events + +These events track [search](/learn/docs/customization/search) and [Ask Fern](/learn/docs/ai-features/ask-fern/overview) usage. + +| Event | Description | Forwarded to | +| --- | --- | --- | +| `ask_ai_suggest` | An Ask Fern suggestion was generated. | None (Fern internal only) | + +## Error events + +These events help identify broken pages and missing content. + +| Event | Description | Forwarded to | +| --- | --- | --- | +| `not_found` | A visitor hit a 404 page. | PostHog, GA4, GTM | + +## CLI and Dashboard events + +The Fern CLI and [Dashboard](https://dashboard.buildwithfern.com) emit their own analytics events for internal product telemetry (command usage, onboarding funnels, billing events, etc.). These aren't forwarded to your analytics providers and are used only by Fern for product improvement. + +CLI telemetry can be disabled by setting the `FERN_TELEMETRY_DISABLED` environment variable or adding `telemetry.enabled: false` to `~/.fernrc`. diff --git a/fern/products/docs/pages/integrations/analytics/posthog.mdx b/fern/products/docs/pages/integrations/analytics/posthog.mdx index 1d1c07f9a..1a5591cd7 100644 --- a/fern/products/docs/pages/integrations/analytics/posthog.mdx +++ b/fern/products/docs/pages/integrations/analytics/posthog.mdx @@ -42,3 +42,5 @@ Integrate PostHog to track user behavior and analytics in your documentation, in + +For a full list of events Fern forwards to your PostHog instance, see the [analytics events reference](/learn/docs/integrations/analytics/events). diff --git a/fern/products/docs/pages/integrations/overview.mdx b/fern/products/docs/pages/integrations/overview.mdx index 6aa25681e..776eacead 100644 --- a/fern/products/docs/pages/integrations/overview.mdx +++ b/fern/products/docs/pages/integrations/overview.mdx @@ -3,8 +3,13 @@ title: Analytics and integrations description: Connect analytics and support tools to your Fern documentation. Set up PostHog, Segment, FullStory, Intercom, and Postman collections. --- +Connect your Fern documentation to the external tools you already use: analytics, session recording, support chat, and developer tools like Postman. Fern emits a set of [analytics events](/learn/docs/integrations/analytics/events) (page views, feedback interactions, API Explorer usage, and more) and forwards them to whichever analytics providers you configure. - +## Supported providers + +### Analytics + + +} + iconSize={12} +/> + +} + iconSize={12} +/> + + + +### Session recording and support + + + + + +### Developer tools + + + -## Enable analytics +## Configure providers -You can define your analytics configuration in `docs.yml`. You only need to include entries for the platforms you want to connect. +Define your provider configuration in `docs.yml`. Include only the providers you want to connect. ```yaml docs.yml analytics: @@ -82,8 +115,7 @@ If your docs configuration is public, don't add secret values directly to `docs. Instead, reference an environment variable by using the syntax `${VARIABLE_NAME}`. -If you are using GitHub Workflows to trigger docs generation, you must make sure that the environment variables -are available during the workflow run. +If you use GitHub Workflows to trigger docs generation, the environment variables must be available during the workflow run. ```yaml {4} - name: Publish Docs @@ -97,7 +129,6 @@ are available during the workflow run. - ## Connect other integrations via custom JavaScript diff --git a/fern/products/docs/pages/preview-publish/preview-changes-locally.mdx b/fern/products/docs/pages/preview-publish/preview-changes-locally.mdx index 666289bf5..cb6d58255 100644 --- a/fern/products/docs/pages/preview-publish/preview-changes-locally.mdx +++ b/fern/products/docs/pages/preview-publish/preview-changes-locally.mdx @@ -13,6 +13,7 @@ Fern offers two ways to preview documentation changes: Install the following: - Node.js version 22 or higher - [The Fern CLI](/learn/cli-api-reference/cli-reference/overview#install-fern-cli) +- [pnpm](https://pnpm.io/installation), available on your `PATH`. `fern docs dev` uses pnpm internally to install the dependencies it needs to render your preview (for example, `esbuild`), so it must be installed globally even if your project uses npm or yarn. ## Local development @@ -55,6 +56,12 @@ Some features are disabled in local development: `fern docs dev` and `fern generate --docs` must be run from a directory that contains a [`fern/` folder](/learn/docs/getting-started/project-structure) with a `docs.yml` inside. Change into your project directory, or add a `docs.yml`. +#### Failed to install required package due to error: Command failed with exit code 1: pnpm i esbuild + +`fern docs dev` shells out to pnpm to install the dependencies it needs to render your preview. Install [pnpm](https://pnpm.io/installation) globally and make sure it's on your `PATH`, then rerun `fern docs dev`. Your project's package manager (npm, yarn, etc.) doesn't need to change. + +If the same command also prints `[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: esbuild`, run `pnpm approve-builds` and approve `esbuild` so pnpm allows its post-install scripts to run. + #### Broken link to /some/path (resolved path: ...) `fern check` reports this when a link in a Markdown page doesn't resolve to a real page, anchor, or file in your docs. diff --git a/fern/products/docs/pages/self-hosted/changelog/2026-05-09.mdx b/fern/products/docs/pages/self-hosted/changelog/2026-05-09.mdx new file mode 100644 index 000000000..c28eea12a --- /dev/null +++ b/fern/products/docs/pages/self-hosted/changelog/2026-05-09.mdx @@ -0,0 +1,47 @@ +### v0.114.44 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.44 +``` + +Digest: `sha256:1af81539eb27cd3c8f5e049581ca48f49388dbbee5a87bdafc30dd3ea8096d6e` + +### v0.114.44 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.44 +``` + +Digest: `sha256:1af81539eb27cd3c8f5e049581ca48f49388dbbee5a87bdafc30dd3ea8096d6e` + +### v0.114.45 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.45 +``` + +Digest: `sha256:402c90cc3b4f043b461a840901f192e1a71ffb06b573e2760b1aa5a5ebff8292` + +### v0.114.45 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.45 +``` + +Digest: `sha256:402c90cc3b4f043b461a840901f192e1a71ffb06b573e2760b1aa5a5ebff8292` + +### v0.114.46 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.46 +``` + +Digest: `sha256:c7aa2e5b00f764469d5310beca727cf29a21694f831bdbb6c34aa9472c44c295` + +### v0.114.46 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.46 +``` + +Digest: `sha256:c7aa2e5b00f764469d5310beca727cf29a21694f831bdbb6c34aa9472c44c295` diff --git a/fern/products/docs/pages/self-hosted/changelog/2026-05-11.mdx b/fern/products/docs/pages/self-hosted/changelog/2026-05-11.mdx new file mode 100644 index 000000000..b8afb05e0 --- /dev/null +++ b/fern/products/docs/pages/self-hosted/changelog/2026-05-11.mdx @@ -0,0 +1,7 @@ +### v0.114.47 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.47 +``` + +Digest: `sha256:23b4cb7e2dc2ccf93a10f1e1ab69247c74b01df4bae211c2268d077cc94922c8` diff --git a/fern/products/docs/pages/self-hosted/changelog/2026-05-12.mdx b/fern/products/docs/pages/self-hosted/changelog/2026-05-12.mdx new file mode 100644 index 000000000..d7e1e3d3b --- /dev/null +++ b/fern/products/docs/pages/self-hosted/changelog/2026-05-12.mdx @@ -0,0 +1,23 @@ +### v0.114.48 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.48 +``` + +Digest: `sha256:46ff081497e53f7fd574fb9cc2b3463761ef4214430246b82d4587f206020079` + +### v0.114.49 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.49 +``` + +Digest: `sha256:392c78851ff5c6964b6973ebf4e8042b52f3e6d7e2404ed36badd00c4fa9e8d0` + +### v0.114.50 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.50 +``` + +Digest: `sha256:8b204fd8cf4a0b47feb6143c7f32859eb81f5a602288d2f087b9d75c6c38718f` diff --git a/fern/products/docs/pages/self-hosted/changelog/2026-05-13.mdx b/fern/products/docs/pages/self-hosted/changelog/2026-05-13.mdx new file mode 100644 index 000000000..7c6aa167b --- /dev/null +++ b/fern/products/docs/pages/self-hosted/changelog/2026-05-13.mdx @@ -0,0 +1,47 @@ +### v0.114.51 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.51 +``` + +Digest: `sha256:0ad7cc2415feaf64340c1321e189c8a7d5a8eaec8f46f94660da74eb9a66fb9a` + +### v0.114.52 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.52 +``` + +Digest: `sha256:eebf6d94b0c7ab6a93c5b303b6489c475a68478893a2457b921dd71d8214c7c4` + +### v0.114.53 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.53 +``` + +Digest: `sha256:9dd10b58913dd82ee3f8cd545b0e7053fe4d5262a42a57190c0afd7cf207c23b` + +### v0.114.54 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.54 +``` + +Digest: `sha256:838ca98a9e6cff98170b5b542ae500d39db06685e5708ee3c1d7e5e3952c3947` + +### v0.114.55 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.55 +``` + +Digest: `sha256:90d4219f24073671c72f05743bd2bfc81c6bf58e09ba3f0bd0e10d46fe600e5c` + +### v0.114.56 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.56 +``` + +Digest: `sha256:7d7226e3bf3311add1733cf2ca820873bb31e90e6d8d754a1b3700464e31b7c1` diff --git a/fern/products/docs/pages/self-hosted/changelog/2026-05-14.mdx b/fern/products/docs/pages/self-hosted/changelog/2026-05-14.mdx new file mode 100644 index 000000000..420969fef --- /dev/null +++ b/fern/products/docs/pages/self-hosted/changelog/2026-05-14.mdx @@ -0,0 +1,31 @@ +### v0.114.57 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.57 +``` + +Digest: `sha256:1b12391e3e70cd667ca4b51f0c115148d48755fab826291e625c4281e643db95` + +### v0.114.58 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.58 +``` + +Digest: `sha256:66cec7597c36fb2992ed2df7e5f71eadb76f5bd0447ad38f483b08c4d97d285b` + +### v0.114.59 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.59 +``` + +Digest: `sha256:06893b60da76937184e06dd0f6fa7c94432fc02a876814bad4f8d35ccd505999` + +### v0.114.60 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.60 +``` + +Digest: `sha256:a1d66fe7456d0f970bc7b5155474bbe0c2cd6b3d2055624524859a6c36833b77` diff --git a/fern/products/docs/pages/self-hosted/changelog/2026-05-15.mdx b/fern/products/docs/pages/self-hosted/changelog/2026-05-15.mdx new file mode 100644 index 000000000..ec3af1e97 --- /dev/null +++ b/fern/products/docs/pages/self-hosted/changelog/2026-05-15.mdx @@ -0,0 +1,31 @@ +### v0.114.61 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.61 +``` + +Digest: `sha256:916c4eccaa6916ca2c97e6322e8be3a5b045c2eb41f7462faeff4d79f92da972` + +### v0.114.62 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.62 +``` + +Digest: `sha256:e27dd7f81899833c32887ed83ab8cf6c54f2cf4bfdc25543d756da3a7f57c967` + +### v0.114.63 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.63 +``` + +Digest: `sha256:c40bc0a5632e05e2ccde7dd3e1a1674bc0d09fda2c2aef7d2211eeae50388ae6` + +### v0.114.64 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.64 +``` + +Digest: `sha256:8081f73e1e5c17ea24c145d4fa45d15384f20cbe002e27f67ac18f3552cf0e10` diff --git a/fern/products/docs/pages/self-hosted/changelog/2026-05-18.mdx b/fern/products/docs/pages/self-hosted/changelog/2026-05-18.mdx new file mode 100644 index 000000000..c8439003c --- /dev/null +++ b/fern/products/docs/pages/self-hosted/changelog/2026-05-18.mdx @@ -0,0 +1,31 @@ +### v0.114.65 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.65 +``` + +Digest: `sha256:406c73053c4ac48f731ef2faa73ca8260f5db79168107be27c225b54be696510` + +### v0.114.66 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.66 +``` + +Digest: `sha256:590e70c00e7672cd7e020b626856155e0be42da51ce4b83df92f81dd72f5000c` + +### v0.114.67 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.67 +``` + +Digest: `sha256:62b517d04ed0b83a8cdbc71aceee161481cafce93da3951e3e738082f80a974c` + +### v0.114.68 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.68 +``` + +Digest: `sha256:b9a7aead0bdee99515125759e1b2e13e6f4e44187b2f7a645d79aff1e7247552` diff --git a/fern/products/docs/pages/self-hosted/changelog/2026-05-19.mdx b/fern/products/docs/pages/self-hosted/changelog/2026-05-19.mdx new file mode 100644 index 000000000..9f5e9006b --- /dev/null +++ b/fern/products/docs/pages/self-hosted/changelog/2026-05-19.mdx @@ -0,0 +1,15 @@ +### v0.114.69 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.69 +``` + +Digest: `sha256:a85e76ad8118bd8c6ecd1b0aaa878750ff0c5e245c6e7f6789a9dd395f8dd213` + +### v0.114.70 + +```dockerfile +FROM fernenterprise/fern-self-hosted:0.114.70 +``` + +Digest: `sha256:ee14b77b22bc7f3610f061dcd089040d7e6b04d84b3660fed52cfa5b8d24f9be` diff --git a/fern/products/docs/pages/seo/redirects.mdx b/fern/products/docs/pages/seo/redirects.mdx index f0e84985b..d1d21cb0b 100644 --- a/fern/products/docs/pages/seo/redirects.mdx +++ b/fern/products/docs/pages/seo/redirects.mdx @@ -14,7 +14,9 @@ subtitle: Learn how to configure redirects in Fern Docs. Set up exact path redir ## Catching missing redirects -You can use [`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check) to automatically detect pages that were removed or moved without a redirect. Configure the [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration) in `docs.yml` to control its severity. +The [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration), run by [`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check), compares the navigation tree built from your local YAML against the most recently **published** state of your site and flags previously-published URLs that no longer resolve and aren't covered by an entry in `redirects:`. This catches pages you've moved or removed before they start returning 404s for existing inbound links. + +Tune severity with the [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration) in `docs.yml`. ## Common errors diff --git a/fern/products/docs/snippets/redirects.mdx b/fern/products/docs/snippets/redirects.mdx index 88049b8d0..55032b68f 100644 --- a/fern/products/docs/snippets/redirects.mdx +++ b/fern/products/docs/snippets/redirects.mdx @@ -66,14 +66,14 @@ settings: -If you have [versions](/docs/configuration/versions) configured, your default version uses unversioned paths (`/docs/getting-started`), while other versions use versioned paths (`/docs/getting-started/v2`). Fern automatically handles version routing by redirecting broken versioned links to the default version and managing canonical URLs. +If you have [versions](/docs/configuration/versions) configured, your default version uses unversioned paths (`/docs/getting-started`), while other versions use versioned paths (`/docs/v2/getting-started`). Fern automatically handles version routing by redirecting broken versioned links to the default version and managing canonical URLs. Avoid redirecting from unversioned to versioned URLs: ```yaml title="docs.yml" redirects: - source: /docs/event-notifications - destination: /docs/event-notifications/v2 # Don't do this + destination: /docs/v2/event-notifications # Don't do this ``` Manually overriding the default versioning behavior can lead to unexpected redirect patterns. diff --git a/fern/products/sdks/deep-dives/generated-sdk.mdx b/fern/products/sdks/deep-dives/generated-sdk.mdx index c358a494c..770bc778c 100644 --- a/fern/products/sdks/deep-dives/generated-sdk.mdx +++ b/fern/products/sdks/deep-dives/generated-sdk.mdx @@ -39,6 +39,14 @@ The inline documentation comes from your API definition. During the SDK generati +## Availability + +When you mark an endpoint with an [availability](/learn/api-definitions/openapi/extensions/availability) status like `deprecated` or `beta`, the generated SDK includes the corresponding doc comment tag on the client method. IDEs display these as warnings and strikethrough styling so your users know which endpoints are stable and which to avoid. + + +![Deprecated method with strikethrough and @deprecated tag in VS Code](../images/availability-deprecated-ide.png) + + ## Error handling When the API returns a 4xx or 5xx status code, the SDK throws an error that includes the status code, error message, response body, and raw response object. @@ -57,7 +65,7 @@ Your SDK users can configure individual requests using language-specific options | Option | Description | Availability | |--------|-------------|--------------| -| Timeouts | Configure request timeouts (default: 30 seconds for C# and PHP, 60 seconds for all other languages) | All languages | +| Timeouts | Configure request timeouts (default: 30 seconds for [C#](/learn/sdks/generators/csharp/configuration#default-timeout-in-seconds) and PHP, 60 seconds for all other languages) | All languages | | [Retries](/sdks/deep-dives/retries-with-backoff) | Configure maximum retries (default: 2 with exponential backoff for 408, 429, and 5xx responses) | All languages except Ruby and Swift | | Custom HTTP client | Override the default HTTP client for unsupported environments or custom requirements | TypeScript, Python, Java, PHP, and Swift | | [aiohttp transport](/learn/sdks/generators/python/aiohttp-support) | Opt into `aiohttp` as the async HTTP transport to resolve DNS concurrency bottlenecks | Python only | diff --git a/fern/products/sdks/deep-dives/self-hosted-versioning.mdx b/fern/products/sdks/deep-dives/self-hosted-versioning.mdx new file mode 100644 index 000000000..2f5552699 --- /dev/null +++ b/fern/products/sdks/deep-dives/self-hosted-versioning.mdx @@ -0,0 +1,213 @@ +--- +title: Self-hosted SDK versioning +description: Compute the next SDK version number from your own CI when self-hosting Fern SDK generation. +--- + + + +When self-hosting, your pipeline picks the version number for each SDK release. Unlike cloud generation, [self-hosted setups](/learn/sdks/deep-dives/self-hosted) need to compute the next version themselves. + +The CLI exposes two workflows for this. Both can be wired into the same generation pipeline: + +- **`--version AUTO`** is the recommended approach. Fern classifies the change against the full SDK output — so changes driven by `generators.yml` settings, a generator version bump, or a CLI version bump are reflected in the version it picks — and writes the changelog entry, PR description, and conventional-commit message for you. This is also the path that continues to receive improvements. +- **`fern ir` + `fern diff`** is the deterministic alternative. It compares the intermediate representation (IR) of your API spec and returns only the computed bump and next version. Because the diff is over the spec alone, it doesn't account for SDK-implementation changes that come from `generators.yml` configuration, generator version, or CLI version — if any of those move, you'll need to bump the version yourself. The rest of the release artifacts (changelog, PR description, commit message) are also yours to write. Use this flow when you need explicit control over how the version number is derived, or when you can't depend on an external LLM provider. + +## `--version AUTO` (recommended) + +Pass `--version AUTO` to `fern generate` and Fern analyzes the diff between the previous and current SDK output, classifies the change as `MAJOR`, `MINOR`, or `PATCH`, and applies the next [semantic version](https://semver.org/) to the generated package. The same analysis also produces: + +- A changelog entry describing what changed +- A PR description summarizing the release +- A [conventional commit](https://www.conventionalcommits.org/) message + + +`--version AUTO` requires: +- A `FERN_TOKEN` for organization verification (same as all self-hosted generation). +- A [GitHub output](/learn/sdks/deep-dives/self-hosted#setup) configured in `generators.yml`, since the pipeline pushes the version bump and changelog back to the SDK repo. + + + + + +Set the provider and model in `generators.yml`: + +```yaml title="generators.yml" +ai: + provider: openai # openai | anthropic | bedrock + model: gpt-4o # any model name the provider accepts +``` + + + + +Export the matching API key so the Fern CLI can call the provider: + +- `OPENAI_API_KEY` for OpenAI +- `ANTHROPIC_API_KEY` for Anthropic +- Standard AWS credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`) for AWS Bedrock + +The diff is sent to the provider's API using your credentials — Fern's infrastructure is not involved in the analysis. + + + + +```bash +FERN_TOKEN= fern generate --local --version AUTO +``` + + + + +## Deterministic versioning with `fern ir` + `fern diff` + +If you'd rather derive the version number yourself, use the `fern ir` and `fern diff` commands to compute the bump from your API definition. This flow has no LLM dependency: `fern diff` walks the intermediate representation (IR) of both specs and returns a deterministic result. + +The workflow has three steps: + + + + +Check out the spec as it was at the last SDK generation and write its IR to disk: + +```bash +fern ir old-ir.json +``` + +Pass `--api ` if your [project defines multiple APIs](/learn/sdks/overview/project-structure). + + + + +Check out the spec at `HEAD` and write its IR to disk: + +```bash +fern ir new-ir.json +``` + + + + +Run `fern diff` with `--from-version` set to the SDK's current version. When `--from-version` is provided, the command prints a JSON object containing the computed bump and the next version: + +```bash +fern diff \ + --from old-ir.json \ + --to new-ir.json \ + --from-version 1.4.2 +``` + +```json +{ + "bump": "minor", + "nextVersion": "1.5.0", + "errors": [] +} +``` + +`bump` is one of `major`, `minor`, `patch`, or `no_change`. Pass `nextVersion` to `fern generate` to release that exact version: + + + +```bash +fern generate --local --version 1.5.0 +``` + + +```bash +fern generate --local --output-version 1.5.0 +``` + + + + + + + +`fern diff` exits with a non-zero status when the computed bump is `major`. This makes it easy to gate breaking changes on a manual review step in CI. + + +### Wiring `fern ir` + `fern diff` into CI + +The non-obvious part is reproducing the IR for the *previous* spec. Each generated SDK records the config repo commit it was generated from in `.fern/metadata.json`: + +```json title=".fern/metadata.json" +{ + "cliVersion": "0.74.0", + "generatorName": "fernapi/fern-python-sdk", + "generatorVersion": "4.0.0", + "originGitCommit": "a1b2c3d4e5f6...", + "requestedVersion": "1.4.2", + "sdkVersion": "1.4.2" +} +``` + +`originGitCommit` is the SHA in the **config repo** that produced the SDK at its current version. Check that commit out, run `fern ir`, then switch back to `HEAD` and run `fern ir` again to produce both inputs to `fern diff`. + + + +The following snippet runs in the config repo on every push to `main` and computes the next version for a Python SDK whose `originGitCommit` and `sdkVersion` are read from the SDK repo: + +```yaml title=".github/workflows/release-sdk.yml" +name: Release SDK + +on: + push: + branches: [main] + +jobs: + release: + runs-on: ubuntu-latest + env: + FERN_TOKEN: ${{ secrets.FERN_TOKEN }} + SDK_REPO: your-org/python-sdk + steps: + - name: Check out config repo + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Set up Fern CLI + uses: fern-api/setup-fern-cli@v1 + + - name: Read previous SDK metadata + id: meta + run: | + curl -fsSL \ + -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \ + -H "Accept: application/vnd.github.raw" \ + "https://api.github.com/repos/${SDK_REPO}/contents/.fern/metadata.json" \ + > metadata.json + echo "old_sha=$(jq -r .originGitCommit metadata.json)" >> "$GITHUB_OUTPUT" + echo "from_version=$(jq -r .sdkVersion metadata.json)" >> "$GITHUB_OUTPUT" + + - name: Generate previous IR + run: | + git checkout ${{ steps.meta.outputs.old_sha }} + fern ir old-ir.json --api + + - name: Generate current IR + run: | + git checkout ${{ github.sha }} + fern ir new-ir.json --api + + - name: Compute next version + id: diff + run: | + result=$(fern diff \ + --from old-ir.json \ + --to new-ir.json \ + --from-version ${{ steps.meta.outputs.from_version }}) || true + bump=$(echo "$result" | jq -r .bump) + if [ "$bump" = "major" ]; then + echo "Computed a major version bump — manual review required before releasing." + exit 1 + fi + echo "next_version=$(echo "$result" | jq -r .nextVersion)" >> "$GITHUB_OUTPUT" + + - name: Generate SDK + run: fern generate --local --group python-sdk --version ${{ steps.diff.outputs.next_version }} +``` + +`fetch-depth: 0` on the checkout step is required so the runner has the history needed to check out `originGitCommit`. Replace the metadata-fetch step with whatever mechanism gives your pipeline access to the SDK repo's `.fern/metadata.json` (a checkout of the SDK repo, a release artifact, an internal API, and so on). + + diff --git a/fern/products/sdks/deep-dives/self-hosted.mdx b/fern/products/sdks/deep-dives/self-hosted.mdx index f4f4d9a97..4567ee772 100644 --- a/fern/products/sdks/deep-dives/self-hosted.mdx +++ b/fern/products/sdks/deep-dives/self-hosted.mdx @@ -13,7 +13,7 @@ Fern SDK generation [runs on Fern's infrastructure by default](/sdks/overview/ho - Has strict compliance or security requirements - Needs full control over your SDK generation process -When you self-host, you're responsible for infrastructure management and SDK distribution. Self-hosted SDK generation includes [all Fern SDK features](/learn/sdks/overview/capabilities). +When you self-host, you're responsible for infrastructure management, SDK distribution, and [computing SDK version numbers](/learn/sdks/deep-dives/self-hosted-versioning). Self-hosted SDK generation includes [all Fern SDK features](/learn/sdks/overview/capabilities). Unless you have specific requirements that prevent using Fern's default hosting, we recommend **using our managed cloud generation solution** for easier setup and maintenance. @@ -120,6 +120,12 @@ Set up GitHub secrets for authentication. In your repository's **Settings** > ** + + +Cloud generation picks SDK version numbers automatically. With self-hosting, your pipeline computes the next version itself — see [Self-hosted SDK versioning](/learn/sdks/deep-dives/self-hosted-versioning) for the two supported workflows. + + + Use the `--local` flag to generate SDKs locally instead of using Fern's cloud infrastructure. You can combine `--local` with `--group` to generate specific SDKs locally. diff --git a/fern/products/sdks/generators/csharp/changelog/2026-05-11.mdx b/fern/products/sdks/generators/csharp/changelog/2026-05-11.mdx new file mode 100644 index 000000000..21cd34dde --- /dev/null +++ b/fern/products/sdks/generators/csharp/changelog/2026-05-11.mdx @@ -0,0 +1,12 @@ +## 2.66.1 +**`(chore):`** Bump the C# SDK and C# model generator containers' Node base image from +`node:22.22-alpine3.23` to `node:24.15-alpine3.23`. Aligns the generators +with the rest of the Fern generator containers on a single Node major +version (Node 24) and picks up Node 24's CVE patches. The bundled npm +11.12.1 in `node:24.15` already ships patched `brace-expansion@5.0.4`, so +the C# SDK's `brace-expansion 2.0.3` replacement step is removed. The +`ip-address` and `picomatch` patches are retained because the bundled +versions in `node:24.15` (10.1.0 and 4.0.3 respectively) are still +vulnerable. + + diff --git a/fern/products/sdks/generators/csharp/changelog/2026-05-12.mdx b/fern/products/sdks/generators/csharp/changelog/2026-05-12.mdx new file mode 100644 index 000000000..286a59eb8 --- /dev/null +++ b/fern/products/sdks/generators/csharp/changelog/2026-05-12.mdx @@ -0,0 +1,11 @@ +## 2.66.2 +**`(chore):`** Patch C# SDK generator container CVEs flagged in the AWS ECR / grype scan. +Switch the apk upgrade to pick up the latest Alpine 3.23 patches (nghttp2, +openssl, libcrypto, libssl, sqlite-libs, expat, etc.), pin a non-vulnerable +set of `System.*` NuGet dependencies, drop the bundled PowerShell warmup +so its vendored `System.Net.Http 4.3.0` / `System.Security.Cryptography.Xml` +DLLs are no longer included in the published image, and clear the +`System.Net.Http 4.3.0` artifact the `/dependencies.csproj` warmup leaves +in the NuGet cache after restore. + + diff --git a/fern/products/sdks/generators/csharp/changelog/2026-05-13.mdx b/fern/products/sdks/generators/csharp/changelog/2026-05-13.mdx new file mode 100644 index 000000000..0f560037a --- /dev/null +++ b/fern/products/sdks/generators/csharp/changelog/2026-05-13.mdx @@ -0,0 +1,5 @@ +## 2.66.3 +**`(fix):`** Bump WireMock.Net from 2.2.0 to 2.6.0 in generated test projects to resolve Snyk +vulnerability reports flagging the older version. + + diff --git a/fern/products/sdks/generators/csharp/changelog/2026-05-15.mdx b/fern/products/sdks/generators/csharp/changelog/2026-05-15.mdx new file mode 100644 index 000000000..2fba96e8e --- /dev/null +++ b/fern/products/sdks/generators/csharp/changelog/2026-05-15.mdx @@ -0,0 +1,7 @@ +## 2.66.4 +**`(fix):`** Dynamic snippets now render path-parameter arguments in IR (URL / SDK signature) order +rather than in the order they happen to appear in the input request, so generated +examples line up with the actual SDK method signature even when the spec lists path +parameters in a different order. + + diff --git a/fern/products/sdks/generators/csharp/configuration.mdx b/fern/products/sdks/generators/csharp/configuration.mdx index 4343ea434..172f16836 100644 --- a/fern/products/sdks/generators/csharp/configuration.mdx +++ b/fern/products/sdks/generators/csharp/configuration.mdx @@ -32,6 +32,10 @@ Sets the name of the generated API client class. This determines the primary cli Customizes the name of the pagination helper class used for handling paginated API responses. This allows you to specify a custom name that fits your naming conventions. + +The default timeout for network requests, in seconds. Set to `infinity` to disable the default timeout. SDK users can still [override this per request](/learn/sdks/deep-dives/sdk-user-features#customization-options) by passing `RequestOptions.Timeout`. + + When enabled, generates enum types that can handle unknown values. This allows the SDK to process new enum values that may be added to the API without breaking existing client code, improving forward compatibility. diff --git a/fern/products/sdks/generators/go/changelog/2026-05-11.mdx b/fern/products/sdks/generators/go/changelog/2026-05-11.mdx new file mode 100644 index 000000000..cfbab0d6b --- /dev/null +++ b/fern/products/sdks/generators/go/changelog/2026-05-11.mdx @@ -0,0 +1,16 @@ +## 1.41.0 +**`(feat):`** Add a `WithFunc` option for bearer auth that accepts a `func() (string, error)` callable. +The callable is evaluated at request time when no static token is set, matching the callable +auth behavior available in the Python and TypeScript SDK generators. + + +## 1.40.4 +**`(chore):`** Bump the Go SDK and Go model generator containers' Node base image from +`node:22.22-alpine3.23` to `node:24.15-alpine3.23`. Aligns the generators +with the rest of the Fern generator containers on a single Node major +version (Node 24) and picks up Node 24's CVE patches. The existing +`npm pack @latest` loop that swaps in patched `ip-address`, +`brace-expansion`, and `picomatch` is retained because `npm pack @latest` +continues to resolve the same fixed releases on Node 24. + + diff --git a/fern/products/sdks/generators/go/changelog/2026-05-12.mdx b/fern/products/sdks/generators/go/changelog/2026-05-12.mdx new file mode 100644 index 000000000..f30629b61 --- /dev/null +++ b/fern/products/sdks/generators/go/changelog/2026-05-12.mdx @@ -0,0 +1,13 @@ +## 1.41.1 +**`(chore):`** Patch Go SDK + Go model generator container CVEs flagged in the AWS ECR / +grype scan. Bump the Go base image to `golang:1.26.3-alpine3.23`, refresh +`apk upgrade`, and patch npm's bundled `picomatch@4.0.3 -> 4.0.4` and +`brace-expansion@5.0.4 -> 5.0.5` via tarball replacement so the published +image no longer ships the vulnerable bundled JS dependencies that grype +flags. Also drop the `internal/testdata/**` test fixtures and clear the +`/go/pkg/mod` + `/root/.cache/go-build` build caches from the runtime +image so grype no longer scans them as a source of stale `yaml.v3` and +`golang.org/x/net` pseudo-versions that are not actually linked into +`/fern-go-sdk`. + + diff --git a/fern/products/sdks/generators/go/changelog/2026-05-13.mdx b/fern/products/sdks/generators/go/changelog/2026-05-13.mdx new file mode 100644 index 000000000..873ddb5e6 --- /dev/null +++ b/fern/products/sdks/generators/go/changelog/2026-05-13.mdx @@ -0,0 +1,8 @@ +## 1.41.2 +**`(fix):`** Stop launching WireMock with `--global-response-templating` in generated +wire-test `docker-compose.test.yml`. Response examples containing literal +`{{...}}` are now served verbatim instead of being passed through +WireMock's Handlebars transformer, which would fail to resolve them as +helpers and return 500. + + diff --git a/fern/products/sdks/generators/go/changelog/2026-05-14.mdx b/fern/products/sdks/generators/go/changelog/2026-05-14.mdx new file mode 100644 index 000000000..67adc2ce2 --- /dev/null +++ b/fern/products/sdks/generators/go/changelog/2026-05-14.mdx @@ -0,0 +1,11 @@ +## 1.41.3 +**`(chore):`** Patch `/usr/local/go/src/go.mod`, `vendor/modules.txt`, and `go.sum` in +the go-sdk + go-model containers so they declare `golang.org/x/net +v0.53.0`. Go 1.26.3 already ships the CVE-2026-33814 fix in its bundled +`h2_bundle.go` (the HTTP/2 SETTINGS_MAX_FRAME_SIZE validation moved to +the top of `ForeachSetting`), but the stdlib SBOM still pins the +pre-fix x/net pseudo-version `v0.47.1-0.20260417*`. Bumping the SBOM +metadata to v0.53.0 makes grype reflect the patched code instead of +flagging the toolchain as vulnerable. + + diff --git a/fern/products/sdks/generators/go/changelog/2026-05-15.mdx b/fern/products/sdks/generators/go/changelog/2026-05-15.mdx new file mode 100644 index 000000000..778bd96b7 --- /dev/null +++ b/fern/products/sdks/generators/go/changelog/2026-05-15.mdx @@ -0,0 +1,7 @@ +## 1.41.4 +**`(fix):`** Dynamic snippets now render path-parameter arguments in IR (URL / SDK signature) order +rather than in the order they happen to appear in the input request, so generated +examples line up with the actual SDK method signature even when the spec lists path +parameters in a different order. + + diff --git a/fern/products/sdks/generators/go/changelog/2026-05-18.mdx b/fern/products/sdks/generators/go/changelog/2026-05-18.mdx new file mode 100644 index 000000000..a490e8516 --- /dev/null +++ b/fern/products/sdks/generators/go/changelog/2026-05-18.mdx @@ -0,0 +1,16 @@ +## 1.42.0 +**`(feat):`** Add streaming reconnect options on every Go SDK request: +`option.WithMaxStreamReconnectAttempts(uint)`, `option.WithoutStreamReconnection()`, +and `option.WithoutRetries()`. + +For SSE endpoints whose Fern definition sets `response-stream.resumable: true` +(or whose OpenAPI sets `x-fern-streaming.resumable: true`), the generated +streaming methods now reconnect transparently on mid-stream connection drops +using SSE `Last-Event-ID` semantics, honoring server-sent `retry:` directives +and capped by `MaxStreamReconnectAttempts` (default 5). + +No behavior change for endpoints that do not opt into `resumable: true`. The +new option constructors are emitted unconditionally and have no effect on +those endpoints. + + diff --git a/fern/products/sdks/generators/java/changelog/2026-05-11.mdx b/fern/products/sdks/generators/java/changelog/2026-05-11.mdx new file mode 100644 index 000000000..1aef556aa --- /dev/null +++ b/fern/products/sdks/generators/java/changelog/2026-05-11.mdx @@ -0,0 +1,16 @@ +## 4.8.5 +**`(chore):`** Bump the Java SDK generator container's Node base image from +`node:24.14.1-bookworm` to `node:24.15-trixie`. Aligns the generator +with the rest of the Fern generator containers on a single Node patch +minor (floating `24.15`) and a single Debian release (trixie). Trixie ships +patched versions of glibc, dpkg, nghttp2, libcap2, systemd, libgcrypt20, +krb5, curl, and expat that are not available on bookworm, clearing the +AWS Inspector findings that dist-upgrade alone could not. The non-slim +variant is intentional because the Node-stage patch steps shell out to +`curl` and `tar`. The bundled npm 11.12.1 in `node:24.15` already ships +patched `glob@13.0.6`, `minimatch@10.2.4`, `tar@7.5.11`, and +`brace-expansion@5.0.4`, so those tarball-replacement patch steps are +removed. The `ip-address` and `picomatch` patches are retained because the +bundled versions (10.1.0 and 4.0.3 respectively) are still vulnerable. + + diff --git a/fern/products/sdks/generators/java/changelog/2026-05-12.mdx b/fern/products/sdks/generators/java/changelog/2026-05-12.mdx new file mode 100644 index 000000000..fecb28fbe --- /dev/null +++ b/fern/products/sdks/generators/java/changelog/2026-05-12.mdx @@ -0,0 +1,17 @@ +## 4.8.7 +**`(fix):`** Fix undiscriminated union deserialization when one member has all-optional fields. +Previously, an all-optional object variant (e.g. `PayMethodCloud`) could greedily +consume a payload intended for a more specific variant with required fields (e.g. +`Check` requiring `achHolder`), because Jackson's `@JsonIgnoreProperties(ignoreUnknown=true)` +silently accepts any JSON object when all fields are optional. The deserializer now +emits guarded members (those with at least one required field) before unguarded +(all-optional) members, ensuring the more specific match wins. + + +## 4.8.6 +**`(chore):`** Patch Java SDK generator container CVEs flagged in the AWS ECR / grype +scan. Patch npm's bundled `brace-expansion@5.0.4 -> 5.0.5` (GHSA-f886-m6hf-6m8v) +via tarball replacement so the published image no longer ships the vulnerable +bundled JS dependency that grype flags on `dev/java-sdk-generator`. + + diff --git a/fern/products/sdks/generators/java/changelog/2026-05-15.mdx b/fern/products/sdks/generators/java/changelog/2026-05-15.mdx new file mode 100644 index 000000000..b0cc58744 --- /dev/null +++ b/fern/products/sdks/generators/java/changelog/2026-05-15.mdx @@ -0,0 +1,9 @@ +## 4.8.8 +**`(fix):`** Dynamic snippets now render path-parameter arguments in IR (URL / SDK signature) order +rather than in the order they happen to appear in the input request, so generated +examples line up with the actual SDK method signature even when the spec lists path +parameters in a different order. Also fixes spurious "not recognized" errors that +were raised for endpoint-level path parameters when both top-level and endpoint-level +path parameters were supplied. + + diff --git a/fern/products/sdks/generators/java/changelog/2026-05-18.mdx b/fern/products/sdks/generators/java/changelog/2026-05-18.mdx new file mode 100644 index 000000000..31b33342f --- /dev/null +++ b/fern/products/sdks/generators/java/changelog/2026-05-18.mdx @@ -0,0 +1,11 @@ +## 4.8.10 +**`(chore):`** Update krb5-libs in the Java SDK generator container to fix +CVE-2026-40356 (integer underflow OOB read) and CVE-2026-40355 +(NULL pointer dereference) in MIT Kerberos 5. + + +## 4.8.9 +**`(chore):`** Fix CVE-2026-41989: update libgcrypt in Docker image to patch heap-based +buffer overflow in gcry_pk_decrypt. + + diff --git a/fern/products/sdks/generators/php/changelog/2026-05-11.mdx b/fern/products/sdks/generators/php/changelog/2026-05-11.mdx new file mode 100644 index 000000000..2f962dd19 --- /dev/null +++ b/fern/products/sdks/generators/php/changelog/2026-05-11.mdx @@ -0,0 +1,7 @@ +## 2.9.4 +**`(chore):`** Bump the PHP SDK and PHP model generator containers' Node base image from +`node:22.22-alpine3.23` to `node:24.15-alpine3.23`. Aligns the generators +with the rest of the Fern generator containers on a single Node major +version (Node 24) and picks up Node 24's CVE patches. + + diff --git a/fern/products/sdks/generators/php/changelog/2026-05-12.mdx b/fern/products/sdks/generators/php/changelog/2026-05-12.mdx new file mode 100644 index 000000000..807ec83cd --- /dev/null +++ b/fern/products/sdks/generators/php/changelog/2026-05-12.mdx @@ -0,0 +1,7 @@ +## 2.9.5 +**`(chore):`** Patch PHP SDK + PHP model generator container CVEs flagged in the AWS ECR / +grype scan. Refresh `apk upgrade --available` to pull the latest Alpine +3.23 security patches and patch npm's bundled `picomatch@4.0.3 -> 4.0.4` +and `brace-expansion@5.0.4 -> 5.0.5` via tarball replacement. + + diff --git a/fern/products/sdks/generators/php/changelog/2026-05-13.mdx b/fern/products/sdks/generators/php/changelog/2026-05-13.mdx new file mode 100644 index 000000000..c29bf172a --- /dev/null +++ b/fern/products/sdks/generators/php/changelog/2026-05-13.mdx @@ -0,0 +1,8 @@ +## 2.9.6 +**`(fix):`** Stop launching WireMock with `--global-response-templating` in generated +wire-test `docker-compose.test.yml`. Response examples containing literal +`{{...}}` are now served verbatim instead of being passed through +WireMock's Handlebars transformer, which would fail to resolve them as +helpers and return 500. + + diff --git a/fern/products/sdks/generators/php/changelog/2026-05-14.mdx b/fern/products/sdks/generators/php/changelog/2026-05-14.mdx new file mode 100644 index 000000000..1bfcadf0d --- /dev/null +++ b/fern/products/sdks/generators/php/changelog/2026-05-14.mdx @@ -0,0 +1,17 @@ +## 2.10.0 +**`(feat):`** Support streaming response bodies in generated PHP SDKs (Server-Sent Events, +NDJSON, and raw text). Endpoints with a `response-stream` now return a typed +`SseStream`, `JsonStream`, or `TextStream` that iterates the response +frame-by-frame and deserializes each one into the declared payload type. +Previously these endpoints were emitted as broken `void` methods that always +threw `ApiException` regardless of HTTP status. + + +## 2.9.7 +**`(chore):`** Patch the bundled `ip-address` to v10.2.0 in the php-sdk container to +address CVE-2026-42338 / GHSA-v2v4-37r5-5v8g (XSS in `Address6` HTML- +emitting methods). npm 11.12.1 (shipped with `node:24.15`) bundles +`ip-address@10.1.0` via `socks`; this overlays the published 10.2.0 +tarball in place at image build time. + + diff --git a/fern/products/sdks/generators/php/changelog/2026-05-15.mdx b/fern/products/sdks/generators/php/changelog/2026-05-15.mdx new file mode 100644 index 000000000..7cdf33bf3 --- /dev/null +++ b/fern/products/sdks/generators/php/changelog/2026-05-15.mdx @@ -0,0 +1,7 @@ +## 2.10.1 +**`(fix):`** Dynamic snippets now render path-parameter arguments in IR (URL / SDK signature) order +rather than in the order they happen to appear in the input request, so generated +examples line up with the actual SDK method signature even when the spec lists path +parameters in a different order. + + diff --git a/fern/products/sdks/generators/python/changelog/2026-05-11.mdx b/fern/products/sdks/generators/python/changelog/2026-05-11.mdx new file mode 100644 index 000000000..4bcd29cf4 --- /dev/null +++ b/fern/products/sdks/generators/python/changelog/2026-05-11.mdx @@ -0,0 +1,10 @@ +## 5.12.4 +**`(chore):`** Bump the Python SDK generator container's Node base image from +`node:22.22-bookworm-slim` to `node:24.15-trixie-slim`. Aligns the +generator with the rest of the Fern generator containers on a single +Node major version (Node 24) and Debian release (trixie). Trixie ships +patched versions of glibc, dpkg, nghttp2, libcap2, systemd, libgcrypt20, +krb5, curl, and expat that are not available on bookworm, clearing the +AWS Inspector findings that dist-upgrade alone could not. + + diff --git a/fern/products/sdks/generators/python/changelog/2026-05-12.mdx b/fern/products/sdks/generators/python/changelog/2026-05-12.mdx new file mode 100644 index 000000000..f1c8ac180 --- /dev/null +++ b/fern/products/sdks/generators/python/changelog/2026-05-12.mdx @@ -0,0 +1,9 @@ +## 5.12.5 +**`(chore):`** Patch Python SDK generator container CVEs flagged in the AWS ECR / grype +scan. Patch npm's bundled `picomatch@4.0.3 -> 4.0.4` +(GHSA-c2c7-rcm5-vvqj, GHSA-3v7f-55p6-f55p) and +`brace-expansion@5.0.4 -> 5.0.5` (CVE-2026-33750) via tarball replacement +so the published image no longer ships the vulnerable bundled JS +dependencies that grype flags. + + diff --git a/fern/products/sdks/generators/python/changelog/2026-05-13.mdx b/fern/products/sdks/generators/python/changelog/2026-05-13.mdx new file mode 100644 index 000000000..942b7ca1c --- /dev/null +++ b/fern/products/sdks/generators/python/changelog/2026-05-13.mdx @@ -0,0 +1,8 @@ +## 5.12.6 +**`(fix):`** Stop launching WireMock with `--global-response-templating` in generated +wire-test `docker-compose.test.yml`. Response examples containing literal +`{{...}}` (e.g. FHIR/IPS template strings) are now served verbatim instead +of being passed through WireMock's Handlebars transformer, which would +fail to resolve them as helpers and return 500. + + diff --git a/fern/products/sdks/generators/python/changelog/2026-05-14.mdx b/fern/products/sdks/generators/python/changelog/2026-05-14.mdx new file mode 100644 index 000000000..0e13c2394 --- /dev/null +++ b/fern/products/sdks/generators/python/changelog/2026-05-14.mdx @@ -0,0 +1,21 @@ +## 5.12.8 +**`(chore):`** Bump Poetry from 1.8.5 to 2.4.1 in the python-sdk and pydantic-model +container images. Clears CVE-2026-34591 (Poetry `<2.3.3` stored credentials +in cleartext when keyring storage was unavailable). pyproject.toml's +`poetry-core` constraint moves from `^1.9.0` to `^2.0.0` to stay in +lockstep with Poetry 2.4.1's bundled `poetry-core 2.4.0` under +`virtualenvs.create=false`. `poetry.lock` regenerated under Poetry 2.4.1. + + +## 5.12.7 +**`(chore):`** Patch the bundled `ip-address` to v10.2.0 in the python-sdk container to +address CVE-2026-42338 / GHSA-v2v4-37r5-5v8g (XSS in `Address6` HTML- +emitting methods). npm 11.12.1 (shipped with `node:24.15`) bundles +`ip-address@10.1.0` via `socks`; this overlays the published 10.2.0 +tarball in place at image build time. Also bumps the container-level +`pip` to 26.1 to clear CVE-2025-8869, CVE-2026-3219, CVE-2026-6357, and +CVE-2026-1703 (self-update flaw running after wheel install). Poetry +stays at 1.8.5 because pyproject.toml's `virtualenvs.create=false` flow +requires `poetry-core ^1.9.0`. + + diff --git a/fern/products/sdks/generators/python/changelog/2026-05-15.mdx b/fern/products/sdks/generators/python/changelog/2026-05-15.mdx new file mode 100644 index 000000000..06960bb20 --- /dev/null +++ b/fern/products/sdks/generators/python/changelog/2026-05-15.mdx @@ -0,0 +1,20 @@ +## 5.12.10 +**`(fix):`** Dynamic snippets now render path-parameter arguments in IR (URL / SDK signature) order +rather than in the order they happen to appear in the input request, so generated +examples line up with the actual SDK method signature even when the spec lists path +parameters in a different order. + + +**`(fix):`** Dynamic snippets now pass root-level path parameters to the endpoint method instead +of the client constructor (which does not accept them), and include them alongside +endpoint-level path parameters so the rendered call matches the generated Python SDK +method signature. + + +## 5.12.9 +**`(fix):`** Bump @fern-api/generator-cli to 0.9.28, which sets explicit author and +committer on API-created commits to the Fern bot identity. Fixes commit +attribution on GitHub Enterprise where PAT-based authentication previously +attributed commits to the PAT-owning service account instead of fern-api[bot]. + + diff --git a/fern/products/sdks/generators/python/changelog/2026-05-18.mdx b/fern/products/sdks/generators/python/changelog/2026-05-18.mdx new file mode 100644 index 000000000..1778d1173 --- /dev/null +++ b/fern/products/sdks/generators/python/changelog/2026-05-18.mdx @@ -0,0 +1,16 @@ +## 5.12.12 +**`(fix):`** Fix `test_aiohttp_autodetect.py` and `_default_clients.py` to use the +configured `package_name` instead of the raw organization name. Previously, +when `package_name` in `generators.yml` differed from `organization` in +`fern.config.json`, the generated aiohttp test used incorrect import paths +and the pip install error message contained a hardcoded literal "package" +instead of the actual package name. + + +## 5.12.11 +**`(chore):`** Update OS packages in the Python SDK generator container from Debian sid to fix +krb5 (CVE-2026-40355, CVE-2026-40356), curl (CVE-2026-1965, CVE-2026-4873, +CVE-2026-5545, CVE-2026-6253, CVE-2026-6429), gnutls28 (CVE-2026-3832), +and expat (CVE-2026-45186). + + diff --git a/fern/products/sdks/generators/ruby/changelog/2026-05-12.mdx b/fern/products/sdks/generators/ruby/changelog/2026-05-12.mdx new file mode 100644 index 000000000..a258410ec --- /dev/null +++ b/fern/products/sdks/generators/ruby/changelog/2026-05-12.mdx @@ -0,0 +1,23 @@ +## 1.12.8 +**`(fix):`** Fix `Layout/EmptyComment` RuboCop offense emitted for types with no +description. The AST `Comment` node now skips writing when `docs` is +empty or whitespace-only, so undocumented model classes no longer +produce a bare `#` line above their class definition. + + +## 1.12.7 +**`(fix):`** Fix `Layout/EmptyComment` RuboCop offense emitted for types with no +description. The AST `Comment` node now skips writing when `docs` is +empty or whitespace-only, so undocumented model classes no longer +produce a bare `#` line above their class definition. + + +## 1.12.6 +**`(chore):`** Patch Ruby SDK generator container CVEs flagged in the AWS ECR / grype +scan. Remove the unused `erb-4.0.3`, `net-imap-0.4.21`, `addressable-2.8.5`, +`rexml-3.2.5`, and `rexml-3.2.6` gem directories (in addition to the +gemspec stubs) and install patched `addressable-2.8.10` + `rexml-3.4.4`, +so grype no longer reports the vulnerable versions vendored alongside +Ruby 3.3's default gems and the rubocop dependency graph. + + diff --git a/fern/products/sdks/generators/ruby/changelog/2026-05-13.mdx b/fern/products/sdks/generators/ruby/changelog/2026-05-13.mdx new file mode 100644 index 000000000..0214ecdd8 --- /dev/null +++ b/fern/products/sdks/generators/ruby/changelog/2026-05-13.mdx @@ -0,0 +1,8 @@ +## 1.12.9 +**`(fix):`** Stop launching WireMock with `--global-response-templating` in generated +wire-test `docker-compose.test.yml`. Response examples containing literal +`{{...}}` are now served verbatim instead of being passed through +WireMock's Handlebars transformer, which would fail to resolve them as +helpers and return 500. + + diff --git a/fern/products/sdks/generators/ruby/changelog/2026-05-14.mdx b/fern/products/sdks/generators/ruby/changelog/2026-05-14.mdx new file mode 100644 index 000000000..d82593a1d --- /dev/null +++ b/fern/products/sdks/generators/ruby/changelog/2026-05-14.mdx @@ -0,0 +1,12 @@ +## 1.12.10 +**`(chore):`** Bump `addressable` from 2.8.10 to 2.9.0 in the ruby-v2 SDK generator +container to clear CVE-2026-35611 (ReDoS in URI template expansion). +Switch the post-install cleanup to `gem cleanup` so older 2.8.x copies +dragged in by rubocop's dependency graph are dropped from the final +image. `rexml` stays pinned at 3.4.4 (past the 3.3.6 CVE-2024-49761 +fix). Also strip the vendored `Gemfile.lock` files inside cached +gems (lint_roller, rbs, typeprof, unicode-emoji) so grype stops +reading their pinned rexml / rdoc / addressable versions as +installed packages. + + diff --git a/fern/products/sdks/generators/ruby/changelog/2026-05-15.mdx b/fern/products/sdks/generators/ruby/changelog/2026-05-15.mdx new file mode 100644 index 000000000..35e127fe1 --- /dev/null +++ b/fern/products/sdks/generators/ruby/changelog/2026-05-15.mdx @@ -0,0 +1,7 @@ +## 1.12.11 +**`(fix):`** Dynamic snippets now render path-parameter arguments in IR (URL / SDK signature) order +rather than in the order they happen to appear in the input request, so generated +examples line up with the actual SDK method signature even when the spec lists path +parameters in a different order. + + diff --git a/fern/products/sdks/generators/rust/changelog/2026-05-11.mdx b/fern/products/sdks/generators/rust/changelog/2026-05-11.mdx new file mode 100644 index 000000000..344d02ae0 --- /dev/null +++ b/fern/products/sdks/generators/rust/changelog/2026-05-11.mdx @@ -0,0 +1,19 @@ +## 0.36.5 +**`(chore):`** Bump the Rust SDK and Rust model generator containers' Node base image from +`node:22.22-alpine3.23` to `node:24.15-alpine3.23`. Aligns the generators +with the rest of the Fern generator containers on a single Node major +version (Node 24) and picks up Node 24's CVE patches. The Rust SDK's +in-place `npm@11.13.0` self-upgrade and the bundled `ip-address` patch are +retained because the Node 24 `npm` ship (`11.12.1`) still vendors +`ip-address@10.1.0`, which is vulnerable to GHSA-v2v4-37r5-5v8g. + + +## 0.36.4 +**`(chore):`** Bump the rust toolchain stage in the rust-sdk and rust-model generator +containers from `rust:1.82-alpine3.20` to `rust:1.91-alpine3.23`. Alpine +3.20 is EOL and ships outdated openssl/musl/busybox/zlib/curl/git; 1.91 +is the lowest rust version Docker Hub publishes for alpine3.23. The +Node runtime stage was already on `node:22.22-alpine3.23`, so there is +no longer any Alpine 3.20 layer anywhere in these images. + + diff --git a/fern/products/sdks/generators/rust/changelog/2026-05-12.mdx b/fern/products/sdks/generators/rust/changelog/2026-05-12.mdx new file mode 100644 index 000000000..7443f7dac --- /dev/null +++ b/fern/products/sdks/generators/rust/changelog/2026-05-12.mdx @@ -0,0 +1,11 @@ +## 0.36.6 +**`(fix):`** Fix generated Rust wire tests for single-URL SDKs and pagination error +tests. The wire test generator no longer emits `config.environment = None;` +when the SDK was generated against a single base URL (since the +`environment` field does not exist on `ClientConfig` in that case). +The synchronous-paginator error-propagation tests now use +`ApiError::Configuration` instead of the non-existent +`ApiError::Serialization` variant, so the generated `pagination.rs` test +module compiles. + + diff --git a/fern/products/sdks/generators/rust/changelog/2026-05-13.mdx b/fern/products/sdks/generators/rust/changelog/2026-05-13.mdx new file mode 100644 index 000000000..040ab6546 --- /dev/null +++ b/fern/products/sdks/generators/rust/changelog/2026-05-13.mdx @@ -0,0 +1,8 @@ +## 0.36.7 +**`(fix):`** Stop launching WireMock with `--global-response-templating` in generated +wire-test `docker-compose.test.yml`. Response examples containing literal +`{{...}}` are now served verbatim instead of being passed through +WireMock's Handlebars transformer, which would fail to resolve them as +helpers and return 500. + + diff --git a/fern/products/sdks/generators/swift/changelog/2026-05-11.mdx b/fern/products/sdks/generators/swift/changelog/2026-05-11.mdx new file mode 100644 index 000000000..67db7330f --- /dev/null +++ b/fern/products/sdks/generators/swift/changelog/2026-05-11.mdx @@ -0,0 +1,7 @@ +## 0.35.5 +**`(chore):`** Bump the Swift SDK and Swift model generator containers' Node base image +from `node:22.22-alpine3.23` to `node:24.15-alpine3.23`. Aligns the +generators with the rest of the Fern generator containers on a single Node +major version (Node 24) and picks up Node 24's CVE patches. + + diff --git a/fern/products/sdks/generators/swift/changelog/2026-05-12.mdx b/fern/products/sdks/generators/swift/changelog/2026-05-12.mdx new file mode 100644 index 000000000..a8bf44a5b --- /dev/null +++ b/fern/products/sdks/generators/swift/changelog/2026-05-12.mdx @@ -0,0 +1,8 @@ +## 0.35.6 +**`(chore):`** Patch Swift SDK + Swift model generator container CVEs flagged in the AWS +ECR / grype scan. Patch npm's bundled `picomatch@4.0.3 -> 4.0.4` and +`brace-expansion@5.0.4 -> 5.0.5` via tarball replacement so the published +image no longer ships the vulnerable bundled JS dependencies that grype +flags. + + diff --git a/fern/products/sdks/generators/swift/changelog/2026-05-14.mdx b/fern/products/sdks/generators/swift/changelog/2026-05-14.mdx new file mode 100644 index 000000000..85987c340 --- /dev/null +++ b/fern/products/sdks/generators/swift/changelog/2026-05-14.mdx @@ -0,0 +1,8 @@ +## 0.35.7 +**`(chore):`** Patch the bundled `ip-address` to v10.2.0 in the swift-sdk container to +address CVE-2026-42338 / GHSA-v2v4-37r5-5v8g (XSS in `Address6` HTML- +emitting methods). npm 11.12.1 (shipped with `node:24.15`) bundles +`ip-address@10.1.0` via `socks`; this overlays the published 10.2.0 +tarball in place at image build time. + + diff --git a/fern/products/sdks/generators/swift/changelog/2026-05-15.mdx b/fern/products/sdks/generators/swift/changelog/2026-05-15.mdx new file mode 100644 index 000000000..1cb379c1a --- /dev/null +++ b/fern/products/sdks/generators/swift/changelog/2026-05-15.mdx @@ -0,0 +1,7 @@ +## 0.35.8 +**`(fix):`** Dynamic snippets now render path-parameter arguments in IR (URL / SDK signature) order +rather than in the order they happen to appear in the input request, so generated +examples line up with the actual SDK method signature even when the spec lists path +parameters in a different order. + + diff --git a/fern/products/sdks/generators/typescript/changelog/2026-05-11.mdx b/fern/products/sdks/generators/typescript/changelog/2026-05-11.mdx new file mode 100644 index 000000000..b6a5c9ee9 --- /dev/null +++ b/fern/products/sdks/generators/typescript/changelog/2026-05-11.mdx @@ -0,0 +1,17 @@ +## 3.70.5 +**`(chore):`** Bump the TypeScript SDK validator container's Node base image to +`node:24.15-trixie-slim`. Aligns the validator with the rest of the +Fern generator containers on a single Node major version (Node 24) on +top of the trixie-slim base introduced for `typescript-sdk-cli` and +`typescript-sdk-validator` by PR #15779. + + +## 3.70.4 +**`(chore):`** Bump the typescript-sdk-cli and typescript-sdk-validator container base +images from `node:*-bookworm-slim` to `node:*-trixie-slim`. Trixie ships +patched versions of glibc, dpkg, nghttp2, libcap2, systemd, libgcrypt20, +krb5, curl, and expat that are not available on bookworm, so dist-upgrade +alone is a no-op for those AWS Inspector findings — the base-image bump +is what actually clears them. + + diff --git a/fern/products/sdks/generators/typescript/changelog/2026-05-12.mdx b/fern/products/sdks/generators/typescript/changelog/2026-05-12.mdx new file mode 100644 index 000000000..1216e3344 --- /dev/null +++ b/fern/products/sdks/generators/typescript/changelog/2026-05-12.mdx @@ -0,0 +1,8 @@ +## 3.70.6 +**`(chore):`** Patch TypeScript SDK generator container CVEs flagged in the AWS ECR / +grype scan. Rebuild the embedded `oxlint-tsgolint@0.22.1` Go binary from +source under `GOTOOLCHAIN=go1.26.3` so the published image no longer +ships the upstream go1.26.2 binary that grype flags for CVE-2026-33811, +CVE-2026-33814, CVE-2026-39820, CVE-2026-39836, and CVE-2026-42499. + + diff --git a/fern/products/sdks/generators/typescript/changelog/2026-05-15.mdx b/fern/products/sdks/generators/typescript/changelog/2026-05-15.mdx new file mode 100644 index 000000000..9a63c7923 --- /dev/null +++ b/fern/products/sdks/generators/typescript/changelog/2026-05-15.mdx @@ -0,0 +1,7 @@ +## 3.70.7 +**`(fix):`** Dynamic snippets now render path-parameter arguments in IR (URL / SDK signature) order +rather than in the order they happen to appear in the input request, so generated +examples line up with the actual SDK method signature even when the spec lists path +parameters in a different order. + + diff --git a/fern/products/sdks/generators/typescript/changelog/2026-05-18.mdx b/fern/products/sdks/generators/typescript/changelog/2026-05-18.mdx new file mode 100644 index 000000000..25e7ef9fd --- /dev/null +++ b/fern/products/sdks/generators/typescript/changelog/2026-05-18.mdx @@ -0,0 +1,7 @@ +## 3.70.8 +**`(chore):`** Update OS packages in the TypeScript SDK generator container from Debian sid to fix +krb5 (CVE-2026-40355, CVE-2026-40356), curl (CVE-2026-1965, CVE-2026-4873, +CVE-2026-5545, CVE-2026-6253, CVE-2026-6429), gnutls28 (CVE-2026-3832), +and expat (CVE-2026-45186). + + diff --git a/fern/products/sdks/images/availability-deprecated-ide.png b/fern/products/sdks/images/availability-deprecated-ide.png new file mode 100644 index 000000000..240cce529 Binary files /dev/null and b/fern/products/sdks/images/availability-deprecated-ide.png differ diff --git a/fern/products/sdks/sdks.yml b/fern/products/sdks/sdks.yml index 2e9f95fc9..1fc3b9540 100644 --- a/fern/products/sdks/sdks.yml +++ b/fern/products/sdks/sdks.yml @@ -256,13 +256,16 @@ navigation: - page: Testing path: ./deep-dives/testing.mdx slug: testing - - section: Hosting + - section: Self-hosting slug: deep-dives collapsed: true contents: - - page: Self-hosted SDKs + - page: Setup path: ./deep-dives/self-hosted.mdx slug: self-hosted + - page: Versioning + path: ./deep-dives/self-hosted-versioning.mdx + slug: self-hosted-versioning - section: Reference contents: - page: generators.yml diff --git a/fern/products/sdks/snippets/basic-auth-params.mdx b/fern/products/sdks/snippets/basic-auth-params.mdx index 8f408f3d2..6b8c3efdb 100644 --- a/fern/products/sdks/snippets/basic-auth-params.mdx +++ b/fern/products/sdks/snippets/basic-auth-params.mdx @@ -30,4 +30,7 @@ auth-schemes: Environment variable name that the SDK will automatically scan for the username or password value. When this environment variable is present, users don't need to explicitly provide the username parameter. Follow naming conventions like `YOUR_APP_USERNAME` or `SERVICE_CLIENT_ID`. + + + Use when your API expects only one half of the basic auth credential pair. When `true`, the field is removed from the generated SDK's public API. The omitted field is treated as an empty string when encoding the `Authorization` header (omitting `password` produces `base64("username:")`; omitting `username` produces `base64(":password")`). When both are omitted, the `Authorization` header is skipped entirely. \ No newline at end of file diff --git a/fern/translations/zh/products/api-def/ferndef/api-yml/environments.mdx b/fern/translations/zh/products/api-def/ferndef/api-yml/environments.mdx index 9f6ece096..333fe2541 100644 --- a/fern/translations/zh/products/api-def/ferndef/api-yml/environments.mdx +++ b/fern/translations/zh/products/api-def/ferndef/api-yml/environments.mdx @@ -1,12 +1,12 @@ --- -title: 环境配置 -description: 列出生产、预发布和开发等环境。 -sidebar-title: 环境配置 +title: 环境 +description: 列出生产、暂存和开发等环境。 +noindex: true --- -您可以指定服务器部署的环境。 +您可以指定部署服务器的环境。 -## 单 URL 环境 +## 单URL环境 ```yaml title="api.yml" name: api @@ -17,9 +17,9 @@ environments: url: https://www.staging.yoursite.com ``` -## 每个环境多个 URL +## 每个环境多个URL -您可以为每个环境指定多个 URL。如果您有微服务架构，并且希望单个 SDK 与多个服务器交互，这将很有帮助。 +您可以为每个环境指定多个URL。如果您有微服务架构，并希望单个SDK与多个服务器交互，这将很有帮助。 ```yaml title="api.yml" environments: @@ -33,7 +33,7 @@ environments: Plants: https://plants.staging.yoursite.com ``` -如果您选择使用此功能，必须为您定义的每个服务指定一个 `url`： +如果您选择使用此功能，必须为定义的每个服务指定一个`url`： ```yaml title="auth.yml" service: @@ -44,7 +44,7 @@ service: ## 默认环境 -您也可以提供默认环境： +您还可以提供默认环境： ```yaml title="api.yml" name: api @@ -56,18 +56,18 @@ environments: default-environment: Production ``` -通过提供默认环境，生成的 SDK 将设置为开箱即用地访问该 URL。 +通过提供默认环境，生成的SDK将设置为开箱即用地访问该URL。 -## URL 模板 +## URL模板 -URL 模板目前仅支持 Python 和 Java SDK 生成。 +URL模板目前仅支持Python和Java SDK生成。 -对于跨多个区域或环境部署的 API，您可以定义带有变量占位符的 URL 模板，SDK 用户可以在运行时进行自定义。要设置此功能： +对于跨多个区域或环境部署的API，您可以定义带有变量占位符的URL模板，SDK用户可以在运行时自定义。设置方法： -1. 在 `urls` 下定义您的静态基础 URL——这些会出现在生成的环境枚举中。 -2. 为每个服务添加带有 `{variable}` 占位符的 `url-templates`（例如，`https://api.{region}.example.com/v1`）。Fern 将这些作为 SDK 中的可配置参数公开。 -3. 提供 `default-urls` 作为具体的回退选项，这样 SDK 用户无需提供变量就能获得开箱即用的客户端。 -4. 为每个服务列出可用的 `variables`，每个变量都有一个 `id`、一个 `default` 值，以及一个可选的 `values` 列表来约束允许的选项。 +1. 在`urls`下定义静态基础URL——这些将出现在生成的环境枚举中。 +2. 为每个服务添加带有`{variable}`占位符的`url-templates`（例如，`https://api.{region}.example.com/v1`）。Fern将这些作为SDK中的可配置参数公开。 +3. 提供`default-urls`作为具体的后备方案，以便SDK用户无需提供变量即可获得开箱即用的客户端。 +4. 列出每个服务的可用`variables`，每个变量具有`id`、`default`值和可选的`values`列表来约束允许的选项。 ```yaml title="api.yml" environments: @@ -106,9 +106,9 @@ default-environment: RegionalApiServer ``` ## 基础路径 -如果您希望所有端点都添加路径前缀，请使用 `base-path`。 +如果您希望所有端点都带有路径前缀，请使用`base-path`。 -在下面的示例中，每个端点都添加了 `/v1` 前缀： +在下面的示例中，每个端点都带有`/v1`前缀： ```yaml title="api.yml" name: api base-path: /v1 @@ -116,7 +116,7 @@ base-path: /v1 ## 受众 -如果您有列出的环境需要过滤，可以利用受众功能。 +如果您有想要筛选的已列出环境，可以利用受众功能。 ```yaml title="api.yml" audiences: @@ -129,4 +129,4 @@ environments: url: https://api.buildwithfern.com audiences: - external -``` \ No newline at end of file +``` diff --git a/fern/translations/zh/products/api-def/ferndef/api-yml/errors.mdx b/fern/translations/zh/products/api-def/ferndef/api-yml/errors.mdx index 2546acd56..527636ef2 100644 --- a/fern/translations/zh/products/api-def/ferndef/api-yml/errors.mdx +++ b/fern/translations/zh/products/api-def/ferndef/api-yml/errors.mdx @@ -1,14 +1,14 @@ --- title: 错误处理 description: 指定错误类型和模式 -sidebar-title: 错误处理 +noindex: true --- -为了以惯用方式生成 SDK，Fern 需要知道在解析端点响应时如何区分不同的错误。 +为了生成符合习惯的 SDK，Fern 需要知道在解析端点响应时如何区分不同的错误。 -### 按状态码区分 +### 通过状态码区分 -您可以指定 Fern 按状态码区分。这意味着在每个端点上，列出的每个错误都必须具有不同的 HTTP 状态码。 +您可以指定 Fern 通过状态码进行区分。这意味着在每个端点上，列出的每个错误都必须具有不同的 HTTP 状态码。 ```yaml @@ -18,9 +18,9 @@ error-discrimination: ``` -### 按错误名称区分 +### 通过错误名称区分 -您可以指定 Fern 按错误名称区分。如果您选择此策略，那么 Fern 将假设每个错误响应都有一个额外的属性来表示错误名称。 +您可以指定 Fern 通过错误名称进行区分。如果选择此策略，则 Fern 将假设每个错误响应都有一个额外的属性来表示错误名称。 如果您使用 Fern 生成服务器端代码，那么此选项提供了最大的灵活性。否则，您可能希望使用状态码区分策略。 @@ -35,7 +35,7 @@ error-discrimination: ### 全局错误 -您可以导入并列出将由每个端点抛出的错误。 +您可以导入和列出将由每个端点抛出的错误。 ```yaml @@ -46,4 +46,4 @@ errors: - commons.NotFoundError - commons.BadRequestError ``` - \ No newline at end of file + diff --git a/fern/translations/zh/products/api-def/ferndef/api-yml/global-configuration.mdx b/fern/translations/zh/products/api-def/ferndef/api-yml/global-configuration.mdx index 8445f0a39..254e72809 100644 --- a/fern/translations/zh/products/api-def/ferndef/api-yml/global-configuration.mdx +++ b/fern/translations/zh/products/api-def/ferndef/api-yml/global-configuration.mdx @@ -1,14 +1,14 @@ --- title: 全局配置 -description: 指定全局请求头、路径参数或查询参数，以包含在每个请求中。 -sidebar-title: 全局配置 +description: 指定全局请求头、路径参数或查询参数，以便在每个请求中包含。 +noindex: true --- `api.yml` 配置支持全局配置，如请求头和路径参数。 ## 全局请求头 -您可以指定要包含在每个请求中的请求头： +您可以指定要在每个请求中包含的请求头： ```yaml @@ -18,11 +18,11 @@ headers: ``` -在 `api.yml` 中定义全局请求头时，您必须[在端点示例中包含它们](/api-definitions/ferndef/examples#examples-with-headers)。 +当您在 `api.yml` 中定义全局请求头时，必须[在端点示例中包含它们](/api-definitions/ferndef/examples#examples-with-headers)。 ## 全局路径参数 -您可以指定要包含在每个请求中的路径参数： +您可以指定要在每个请求中包含的路径参数： ```yaml @@ -36,7 +36,7 @@ path-parameters: ### 覆盖基础路径 -如果您有某些端点不在配置的 `base-path` 下，您可以在端点级别覆盖 `base-path`。 +如果您有某些端点不位于配置的 `base-path` 下，可以在端点级别覆盖 `base-path`。 ```yml imdb.yml {5} service: @@ -51,12 +51,12 @@ service: ## 全局查询参数 -目前还不能指定要包含在每个请求中的查询参数。 -如果您希望看到这个功能，请为[此问题](https://github.com/fern-api/fern/issues/2930)投票。 +您还不能指定要在每个请求中包含的查询参数。 +如果您希望看到此功能，请为[此问题](https://github.com/fern-api/fern/issues/2930)投票。 ## 幂等性请求头 -配置幂等性请求头来定义 [SDK 用户](/learn/sdks/deep-dives/idempotency)可以为安全请求重试指定的请求头。您还必须[将每个端点标记为幂等](/learn/api-definitions/ferndef/endpoints/overview#idempotent-endpoints)才能公开这些请求头。当两者都配置时，Fern 生成的 SDK 会将这些请求头作为幂等端点调用的参数公开。 +配置幂等性请求头以定义 [SDK 用户](/learn/sdks/deep-dives/idempotency)可以为安全请求重试指定的请求头。您还必须[将每个端点标记为幂等](/learn/api-definitions/ferndef/endpoints/overview#idempotent-endpoints)才能公开这些请求头。当两者都配置时，Fern 生成的 SDK 会将这些请求头作为幂等端点调用的参数公开。 ```yaml title="api.yml" name: api @@ -66,4 +66,4 @@ idempotency-headers: Idempotency-Expiration: optional ``` -`idempotency-headers` 中的每个键是 HTTP 请求头名称，值是类型。然后 [SDK 用户](/learn/sdks/deep-dives/idempotency)可以在调用幂等端点时指定这些请求头。 \ No newline at end of file +`idempotency-headers` 中的每个键都是 HTTP 请求头名称，值是类型。[SDK 用户](/learn/sdks/deep-dives/idempotency)然后可以在调用幂等端点时指定这些请求头。 diff --git a/fern/translations/zh/products/api-def/ferndef/api-yml/overview.mdx b/fern/translations/zh/products/api-def/ferndef/api-yml/overview.mdx index fc5c27f04..76cfe2288 100644 --- a/fern/translations/zh/products/api-def/ferndef/api-yml/overview.mdx +++ b/fern/translations/zh/products/api-def/ferndef/api-yml/overview.mdx @@ -1,10 +1,10 @@ --- title: api.yml 配置文件 -description: 使用 Fern Definition 格式时，api.yml 文件包含通用 API 配置。 -sidebar-title: api.yml 配置文件 +description: 在使用 Fern Definition 格式时，api.yml 文件包含通用 API 配置。 +noindex: true --- -`fern/` 文件夹中有一个名为 `api.yml` 的特殊文件，其中包含所有 API 级别的配置。 +一个 `fern/` 文件夹包含一个名为 `api.yml` 的特殊文件，其中包括所有 API 范围的配置。 ```bash {5} fern/ @@ -19,7 +19,7 @@ fern/ ## API 名称 -此名称用于在您的组织中唯一标识您的 API。如果您只有一个 API，那么 `api` 是一个合适的名称。 +此名称用于在您的组织中唯一标识您的 API。如果您只有一个 API，那么 `api` 就是一个足够的名称。 ```yaml @@ -42,7 +42,7 @@ docs: | ## API 版本 -您可以定义基于请求头的 API 版本控制方案，例如 `X-API-Version`。支持的版本和默认值的指定方式如下： +您可以定义基于请求头的 API 版本控制方案，例如 `X-API-Version`。支持的版本和默认值指定如下： ```yaml @@ -54,4 +54,4 @@ version: - "2.0.0" - "latest" ``` - \ No newline at end of file + diff --git a/fern/translations/zh/products/api-def/ferndef/audiences.mdx b/fern/translations/zh/products/api-def/ferndef/audiences.mdx index c0f34a865..8c685ef4a 100644 --- a/fern/translations/zh/products/api-def/ferndef/audiences.mdx +++ b/fern/translations/zh/products/api-def/ferndef/audiences.mdx @@ -1,27 +1,26 @@ --- -title: Fern Definition 中的受众 -subtitle: 在您的 Fern Definition 中使用受众，为不同的 API 消费者群体进行分组。 -sidebar-title: Fern Definition 中的受众 +title: Fern 定义中的受众 +subtitle: 在 Fern 定义中使用受众来为不同的 API 消费者群体进行分段。 +noindex: true --- - -受众是为不同消费者分组 API 的有用工具。您可以配置 Fern Docs 发布特定于某个`受众`的文档。您也可以在 [OpenAPI 规范中使用受众](/learn/api-definitions/openapi/extensions/audiences)。 +受众是一个用于为不同消费者分段 API 的有用工具。您可以配置 Fern Docs 来发布特定于某个`受众`的文档。您也可以[在 OpenAPI 规范中使用受众](/learn/api-definitions/openapi/extensions/audiences)。 受众的常见示例包括： - 内部消费者（例如，使用 API 的前端开发人员） -- Beta 测试人员 +- Beta 测试者 - 客户 -默认情况下，如果未指定受众，则所有消费者都可以访问。 +默认情况下，如果没有指定受众，所有消费者都可以访问。 ## 配置 -Fern Definition 具有为不同端点、类型和属性标记不同受众的一级概念。 +Fern 定义具有为不同端点、类型和属性标记不同受众的一级概念。 -要在 Fern Definition 中使用受众，请将其添加到 `api.yml` 中。 +要在 Fern 定义中使用受众，请将其添加到 `api.yml` 中。 在下面的示例中，我们为 `internal`、`beta` 和 `customer` 群体创建了受众： @@ -33,7 +32,7 @@ audiences: - customers ``` -## 端点的受众 +## 端点受众 要为特定消费者标记端点，请添加包含相关群体的 `audience`。 @@ -51,9 +50,9 @@ service: ... ``` -## 类型的受众 +## 类型受众 -类型也可以标记为不同的受众。 +类型也可以为不同受众进行标记。 在此示例中，`Email` 类型对内部和 beta 消费者可用： @@ -67,9 +66,9 @@ Email: - beta ``` -## 属性的受众 +## 属性受众 -类型的属性也可以标记为不同的受众。 +类型的属性也可以为不同受众进行标记。 在此示例中，`to` 属性仅对 beta 消费者可用： @@ -85,7 +84,7 @@ Email: - beta ``` -## SDK 的受众 +## SDK 受众 在 `generators.yml` 中，您可以应用受众过滤器，以便只有某些端点传递给生成器。 @@ -100,11 +99,11 @@ groups: ... ``` -## 文档的受众 +## 文档受众 如果生成 Fern Docs，请更新您的 `docs.yml` 配置以包含您的受众。 -以下示例展示了如何配置您的 `docs.yml` 为 `customers` 受众发布文档： +以下示例显示如何配置 `docs.yml` 来为 `customers` 受众发布文档： ```yaml {3-4} @@ -113,4 +112,4 @@ navigation: audiences: - customers ``` - \ No newline at end of file + diff --git a/fern/translations/zh/products/api-def/ferndef/auth.mdx b/fern/translations/zh/products/api-def/ferndef/auth.mdx index dfbf786e0..b8f38a350 100644 --- a/fern/translations/zh/products/api-def/ferndef/auth.mdx +++ b/fern/translations/zh/products/api-def/ferndef/auth.mdx @@ -1,17 +1,17 @@ --- title: 身份验证 -description: 在 Fern Definition 中配置 API 身份验证。为您的 API 端点设置 bearer token、基本身份验证、自定义头部和 OAuth。 -sidebar-title: 身份验证 +description: 在 Fern Definition 中配置 API 身份验证。为您的 API 端点设置 bearer token、基本认证、自定义标头和 OAuth。 +noindex: true --- -身份验证方案的配置在 `api.yml` 文件中进行。所有 Fern 生成的 SDK 都支持直接配置和环境变量来配置身份验证凭据。 +身份验证方案的配置在 `api.yml` 文件中进行。所有 Fern 生成的 SDK 都支持身份验证凭据的直接配置和环境变量配置。 ```bash {5} fern/ -├─ fern.config.json # 根级别配置 -├─ generators.yml # 你正在使用的生成器 +├─ fern.config.json # 根级配置 +├─ generators.yml # 您正在使用的生成器 └─ definition/ - ├─ api.yml # API 级别配置 + ├─ api.yml # API 级配置 └─ imdb.yml # 端点、类型和错误 ``` @@ -24,7 +24,7 @@ auth-schemes: ``` -要在所有端点中应用身份验证方案，请在 `api.yml` 文件的 `auth` 部分中引用 `auth-scheme`。 +要在所有端点应用身份验证方案，请在 `api.yml` 文件的 `auth` 部分中引用 `auth-scheme`。 ```yaml api.yml {1} auth: AuthScheme auth-schemes: @@ -44,7 +44,7 @@ auth-schemes: scheme: bearer ``` -这将生成一个 SDK，用户需要提供一个名为 `token` 的必需参数。 +这将生成一个 SDK，用户必须提供一个名为 `token` 的必需参数。 ```ts index.ts const client = new Client({ @@ -52,7 +52,7 @@ const client = new Client({ }) ``` -如果你想控制变量命名和要扫描的环境变量，请使用以下配置： +如果您想控制变量命名和要扫描的环境变量，请使用以下配置： ```yaml title="api.yml" {5-7} auth: Bearer @@ -64,14 +64,14 @@ auth-schemes: env: PLANTSTORE_API_KEY ``` -生成的 SDK 会是这样： +生成的 SDK 将如下所示： ```ts index.ts // 使用 process.env.PLANTSTORE_API_KEY let client = new Client(); -// token 已被重命名为 apiKey +// token 已重命名为 apiKey client = new Client({ apiKey: "ey34..." }) @@ -88,7 +88,7 @@ auth-schemes: scheme: basic ``` -这将生成一个 SDK，用户需要提供名为 `username` 和 `password` 的必需参数。 +这将生成一个 SDK，用户必须提供名为 `username` 和 `password` 的必需参数。 ```ts index.ts const client = new Client({ @@ -97,7 +97,7 @@ const client = new Client({ }) ``` -如果你想控制变量命名和要扫描的环境变量，请使用以下配置： +如果您想控制变量命名和要扫描的环境变量，请使用以下配置： ```yaml title="api.yml" {5-11} auth: Basic @@ -112,23 +112,23 @@ auth-schemes: env: PLANTSTORE_CLIENT_SECRET ``` -生成的 SDK 会是这样： +生成的 SDK 将如下所示： ```ts index.ts // 使用 process.env.PLANTSTORE_CLIENT_ID 和 process.env.PLANTSTORE_CLIENT_SECRET let client = new Client(); -// 参数已被重命名 +// 参数已重命名 client = new Client({ clientId: "joeschmoe", clientSecret: "ey34..." }) ``` -## 自定义头部（例如 API 密钥） +## 自定义标头（例如 API key） -你也可以使用自定义头部创建自己的身份验证方案。 +您还可以使用自定义标头创建自己的身份验证方案。 ```yaml title="api.yml" {3-5} auth: ApiKeyAuthScheme @@ -138,7 +138,7 @@ auth-schemes: type: string ``` -这将生成一个 SDK，用户需要提供一个名为 `apiKey` 的必需参数。 +这将生成一个 SDK，用户必须提供一个名为 `apiKey` 的必需参数。 ```ts index.ts const client = new Client({ @@ -146,7 +146,7 @@ const client = new Client({ }) ``` -如果你想控制变量命名和要扫描的环境变量，请使用以下配置： +如果您想控制变量命名和要扫描的环境变量，请使用以下配置： ```yaml title="api.yml" {7-8} auth: ApiKeyAuthScheme @@ -158,14 +158,14 @@ auth-schemes: env: PLANTSTORE_API_KEY ``` -生成的 SDK 会是这样： +生成的 SDK 将如下所示： ```ts index.ts // 使用 process.env.PLANTSTORE_API_KEY let client = new Client(); -// 参数已被重命名 +// 参数已重命名 client = new Client({ apiKey: "ey34..." }) @@ -175,7 +175,7 @@ client = new Client({ -如果你的 API 使用 OAuth，你可以在 `api.yml` 中指定 oauth 方案，并在单独的 `auth.yml` 文件中定义令牌检索端点（[示例](https://github.com/fern-api/fern/blob/3137938b70e058f3691ddef34d5c1cc29acc4b80/test-definitions/fern/apis/oauth-client-credentials/definition/api.yml)）。 +如果您的 API 使用 OAuth，您可以在 `api.yml` 中指定 oauth 方案，并在单独的 `auth.yml` 文件中定义令牌检索端点（[示例](https://github.com/fern-api/fern/blob/3137938b70e058f3691ddef34d5c1cc29acc4b80/test-definitions/fern/apis/oauth-client-credentials/definition/api.yml)）。 ```yaml api.yml name: api @@ -193,18 +193,18 @@ auth-schemes: get-token: endpoint: auth.getTokenWithClientCredentials request-properties: - client-id: $request.client_id # 格式: parameter-name: $request.property_name - client-secret: $request.client_secret # 格式: parameter-name: $request.property_name + client-id: $request.client_id # 格式：参数名: $request.属性名 + client-secret: $request.client_secret # 格式：参数名: $request.属性名 response-properties: - access-token: $response.access_token # 格式: parameter-name: $response.property_name - expires-in: $response.expires_in # 格式: parameter-name: $response.property_name + access-token: $response.access_token # 格式：参数名: $response.属性名 + expires-in: $response.expires_in # 格式：参数名: $response.属性名 ``` -`request-properties` 和 `response-properties` 将 OAuth 标准参数映射到在 `auth.yml` 中定义的实际端点的请求和响应字段名称。 +`request-properties` 和 `response-properties` 将 OAuth 标准参数映射到您在 `auth.yml` 中定义的实际端点的请求和响应字段名称。 - 如果设置了 `expires-in` 属性，生成的 OAuth 令牌提供程序将在令牌过期时自动刷新令牌。否则，假设访问令牌永久有效。 + 如果设置了 `expires-in` 属性，生成的 OAuth 令牌提供程序将在令牌过期时自动刷新令牌。否则，假设访问令牌是永久有效的。 相应的 `auth.yml` 文件（[示例](https://github.com/fern-api/fern/blob/3137938b70e058f3691ddef34d5c1cc29acc4b80/test-definitions/fern/apis/oauth-client-credentials/definition/auth.yml)）定义了令牌端点： @@ -238,13 +238,13 @@ service: response: TokenResponse ``` -如果你的 OAuth 服务器托管在与主 API 不同的 URL 上，你可以使用[每个环境多个 URL](/api-definitions/ferndef/api-yml/environments#multiple-urls-per-environment) 为身份验证和 API 调用指定单独的基础 URL。 +如果您的 OAuth 服务器托管在与主 API 不同的 URL 上，您可以使用[每个环境多 URL](/api-definitions/ferndef/api-yml/environments#multiple-urls-per-environment) 来为身份验证和 API 调用指定单独的基础 URL。 -有了这些，所有的 OAuth 逻辑都会在生成的 SDK 中自动处理。只要你配置了这些设置，你的客户端将自动检索访问令牌并根据需要刷新它。 +有了这些设置，所有 OAuth 逻辑会在生成的 SDK 中自动处理。只要您配置了这些设置，您的客户端将自动检索访问令牌并根据需要刷新它。 -在使用文档 playground 时，可以选择设置 `token-header` 和 `token-prefix` 来自定义头部键名和头部值前缀，以匹配 API 身份验证方案的预期格式。 +在使用文档操作界面时，可以选择性地设置 `token-header` 和 `token-prefix` 来自定义标头键名和标头值前缀，以匹配 API 身份验证方案的预期格式。 -例如，以下配置将产生头部 `Fern-Authorization: Fern-Bearer `： +例如，以下配置将产生标头 `Fern-Authorization: Fern-Bearer `： ```yaml api.yml {5-6} auth-schemes: @@ -255,4 +255,4 @@ auth-schemes: token-prefix: Fern-Bearer get-token: ... -``` \ No newline at end of file +``` diff --git a/fern/translations/zh/products/api-def/ferndef/availability.mdx b/fern/translations/zh/products/api-def/ferndef/availability.mdx index edaa5f2d1..715a8f938 100644 --- a/fern/translations/zh/products/api-def/ferndef/availability.mdx +++ b/fern/translations/zh/products/api-def/ferndef/availability.mdx @@ -1,18 +1,25 @@ --- title: Fern Definition 中的可用性 -description: 向 Fern Definition API 服务、端点、类型或属性添加可用性标识，以指示其发布状态。 -sidebar-title: 可用性 +description: 向 Fern Definition API 服务、端点、类型或属性添加可用性，以指示其发布状态。 +noindex: true --- -您可以在 Fern Definition 中为端点、类型或属性添加 `availability`。您可以在 [`docs.yml` 文件](/learn/docs/configuration/site-level-settings)中配置 API 参考文档各部分的 `availability`。 +您可以在 Fern Definition 中向端点、类型或属性添加 `availability`。您可以在 [`docs.yml` 文件](/learn/docs/configuration/site-level-settings)中配置 API Reference 文档中各部分的 `availability`。 ## 端点、类型和属性 可用性可以是： -- `in-development` 表示正在开发中；将显示 `Beta` 标签 -- `pre-release` 表示可用；将显示 `Beta` 标签 -- `deprecated` 表示将来会被移除；将显示 `Deprecated` 标签 -- `generally-available` 表示稳定且可供使用；将显示 `GA` 标签 + +| 值 | 描述 | 标签 | +| --- | --- | --- | +| `alpha` | 早期实验性发布 | `Alpha` | +| `in-development` | 正在开发中 | `Beta` | +| `beta` | 可用但可能会改变 | `Beta` | +| `pre-release` | 可用 | `Beta` | +| `preview` | 功能完整但可能会改变 | `Preview` | +| `generally-available` | 稳定且可用 | `GA` | +| `deprecated` | 将来会被移除 | `Deprecated` | +| `legacy` | 已被替代但仍然支持 | `Legacy` | ### 端点 @@ -100,4 +107,4 @@ service: ## 部分 - \ No newline at end of file + diff --git a/fern/translations/zh/products/api-def/ferndef/depending-on-other-apis.mdx b/fern/translations/zh/products/api-def/ferndef/depending-on-other-apis.mdx index f5b091f9a..4e28e5473 100644 --- a/fern/translations/zh/products/api-def/ferndef/depending-on-other-apis.mdx +++ b/fern/translations/zh/products/api-def/ferndef/depending-on-other-apis.mdx @@ -1,19 +1,19 @@ --- title: "依赖其他 API" subtitle: 导入 API 定义以生成统一的 SDK -sidebar-title: 依赖其他 API +noindex: true --- -Fern 允许您将其他 API 导入到您的 API 中。 +Fern 允许你将其他 API 导入到你的 API 中。 这在以下情况下通常很有用： -- 您希望在您的 API 中重用另一个 API 的类型 -- 您希望将多个微服务的 API 合并到一个 SDK 中（类似于 AWS SDK） +- 你想在你的 API 中重用另一个 API 的类型 +- 你想将多个微服务的 API 组合成一个 SDK（类似于 AWS SDK） -## 注册依赖的 API +## 注册依赖 API -第一步是**注册**您要依赖的 API。为此，使用 `register` 命令： +第一步是**注册**你想要依赖的 API。为此，使用 `register` 命令： ``` $ fern register @@ -23,7 +23,7 @@ $ fern register ## 依赖已注册的 API -要添加对另一个 API 的依赖，您必须添加一个 `dependencies.yml` 来声明您希望依赖的 API。 +要添加对另一个 API 的依赖，你必须添加一个 `dependencies.yml` 来声明你希望依赖的 API。 @@ -37,14 +37,14 @@ $ fern register -您的 `dependencies.yml` 包含您希望依赖的所有 API 列表： +你的 `dependencies.yml` 包含你希望依赖的所有 API 的列表： ```yaml dependencies.yml dependencies: "@fern/some-dependency": "0.0.1" ``` -接下来，您需要在您的 Fern 定义中创建一个文件夹来容纳依赖项。在文件夹内，创建一个特殊文件 `__package__.yml`，该文件指定您要添加的依赖项和版本。 +接下来，你需要在 Fern 定义中创建一个文件夹来存放依赖。在文件夹内，创建一个特殊文件 `__package__.yml`，用于指定你想要添加的依赖和版本。 @@ -66,4 +66,4 @@ export: dependency: "@fern/some-dependency" ``` -当您使用 `fern generate` 生成 SDK 时，`__package__.yml` 文件将有效地被您所依赖的 API 替换。 \ No newline at end of file +当你使用 `fern generate` 生成 SDK 时，`__package__.yml` 文件将被你所依赖的 API 有效替换。 diff --git a/fern/translations/zh/products/api-def/ferndef/endpoints.mdx b/fern/translations/zh/products/api-def/ferndef/endpoints.mdx index b83cb83f6..006023098 100644 --- a/fern/translations/zh/products/api-def/ferndef/endpoints.mdx +++ b/fern/translations/zh/products/api-def/ferndef/endpoints.mdx @@ -1,18 +1,19 @@ --- -title: Fern 定义中的端点 -description: 在 Fern 定义中将相关的 API 端点组织到服务中，并定义每个端点的 URL、HTTP 方法、请求、响应、错误等。 -sidebar-title: 端点 +title: Fern Definition 中的端点 +description: 在 Fern Definition 中将相关的 API 端点组织成服务，并定义每个端点的 URL、HTTP 方法、请求、响应、错误等。 +noindex: true --- -在 Fern 中，您可以将相关的端点组织到一个**服务**中。这种分组方式提高了清晰度，使生成的 SDK 更加符合习惯。 +在 Fern 中，您将相关端点组织成一个 **Service（服务）**。这种分组 +提高了清晰度，并使生成的 SDK 更加地道。 ## 服务定义 每个服务定义： -1. 一个**基础路径**：所有端点 HTTP 路径的共同前缀 +1. **base-path（基础路径）**：所有端点 HTTP 路径的通用前缀 2. 服务是否需要[身份验证](/learn/api-definitions/ferndef/authentication) -3. **端点** +3. **Endpoints（端点）** ```yaml @@ -24,16 +25,16 @@ sidebar-title: 端点 - 要定义空基础路径的服务，请使用空字符串：`base-path: ""` + 要定义具有空基础路径的服务，请使用空字符串：`base-path: ""` -### 章节显示名称 +### 节显示名称 -默认情况下，API 参考中的章节名称来源于服务文件名（例如，`user.yml` 变成 "User"）。要覆盖章节的显示名称，[请在 `docs.yml` 中使用 `section` 属性](/docs/api-references/customize-api-reference-layout#renaming-sections)。 +默认情况下，API 参考中的节名称来自服务文件名（例如，`user.yml` 变成"User"）。要覆盖节的显示名称，[在您的 `docs.yml` 中使用 `section` 属性](/docs/api-references/customize-api-reference-layout#renaming-sections)。 ### SDK 方法名称 -SDK 方法名称直接从服务文件名和端点键派生而来。文件名成为命名空间，端点键成为方法名称。 +SDK 方法名称直接从服务文件名和端点键派生。文件名成为命名空间，端点键成为方法名。 例如，给定以下定义： @@ -56,13 +57,13 @@ Fern 生成一个名为 `client.users.create()` 的方法。 端点包括： -- 一个 **URL 路径** _（可选择性地包括路径参数）_ -- 一个**显示名称** _（可选）_ -- 一个 **HTTP 方法** +- **URL 路径** _（可选择包含路径参数）_ +- **显示名称** _（可选）_ +- **HTTP 方法** - **请求信息** _（可选）_ - - **查询参数** - - **标头** - - **请求体** + - **Query-parameters（查询参数）** + - **Headers（请求头）** + - **Request body（请求体）** - **成功（200）响应**信息 _（可选）_ - 此端点可能返回的**错误（非 200）响应** _（可选）_ @@ -92,7 +93,7 @@ service: 显示名称将作为端点的标题出现。默认情况下，显示名称等于端点名称的"标题大小写"。如果您想要自定义端点名称，可以**设置显示名称**。 -在下面的示例中，["Add a new plant to the store"](https://plantstore.dev/api-reference/plant-store-api/plants/add-plant) 显示为 API 参考中端点页面的标题。 +在下面的示例中，["Add a new plant to the store"](https://plantstore.dev/api-reference/plant-store-api/plants/add-plant) 作为 API 参考中端点页面的标题显示。 ```yaml {7} @@ -153,7 +154,7 @@ service: path: /all method: GET request: - # 符合习惯的 SDK 需要这个名称 + # 这个名称对于地道的 SDK 是必需的 name: GetAllUsersRequest query-parameters: limit: optional @@ -162,7 +163,10 @@ service: #### `allow-multiple` -使用 `allow-multiple` 指定查询参数在 URL 中允许多次出现，如 `?filter=jane&filter=smith`。这将修改生成的 SDK，以便使用者可以为查询参数提供多个值。 +使用 `allow-multiple` 指定查询参数在 URL 中允许 +多次出现，如 `?filter=jane&filter=smith`。这将改变 +生成的 SDK，使消费者可以为查询 +参数提供多个值。 ```yaml {5} @@ -174,9 +178,9 @@ service: ``` -### 身份验证 +### 认证 -每个端点可以覆盖服务中指定的身份验证行为。 +每个端点都可以覆盖服务中指定的认证行为。 ```yaml @@ -187,15 +191,15 @@ service: getMe: path: "" method: GET - # 这个端点将进行身份验证 + # 此端点将进行认证 auth: true - docs: 根据 Authorization 标头返回当前用户。 + docs: 基于 Authorization 头返回当前用户。 ``` -### 标头 +### 请求头 -每个端点可以指定请求标头： +每个端点可以指定请求头： ```yaml @@ -207,14 +211,14 @@ service: path: /all method: GET request: - # 符合习惯的 SDK 需要这个名称 + # 这个名称对于地道的 SDK 是必需的 name: GetAllUsersRequest headers: X-Endpoint-Header: string ``` -服务也可以指定请求标头。这些标头将级联到服务的端点。 +服务也可以指定请求头。这些头将级联到服务的端点。 ```yaml {4-5} @@ -228,7 +232,7 @@ service: path: /all method: GET request: - # 符合习惯的 SDK 需要这个名称 + # 这个名称对于地道的 SDK 是必需的 name: GetAllUsersRequest headers: X-Endpoint-Header: string @@ -256,7 +260,8 @@ service: #### 内联请求体 -如果请求体是一个对象，您可以**内联类型声明**。这使生成的 SDK 更加符合习惯。 +如果请求体是一个对象，您可以**内联类型声明**。这 +使生成的 SDK 更加地道。 ```yaml @@ -268,7 +273,7 @@ service: path: /create method: POST request: - # 符合习惯的 SDK 需要这个名称 + # 这个名称对于地道的 SDK 是必需的 name: CreateUserRequest body: properties: @@ -278,7 +283,8 @@ service: ### 成功响应 -端点可以指定 `response`，这是成功（200）调用时将返回的体的类型。 +端点可以指定 `response`，这是在成功（200）调用时 +返回的主体类型。 ```yaml @@ -327,14 +333,14 @@ types: ### 分页 -Fern 支持偏移量、游标、URI 和基于路径的分页方案。要在[生成的 SDK](/learn/sdks/deep-dives/auto-pagination) 中设置自动分页： +Fern 支持偏移、游标、URI 和基于路径的分页方案。要在[生成的 SDK](/learn/sdks/deep-dives/auto-pagination) 中设置自动分页： 1. 使用 `pagination` 字段标注所需的分页端点 -2. 指定分页方案（`offset`、`cursor`、`next_uri` 或 `next_path`） -3. 使用点访问表示法指定 `results` 的位置。 +1. 指定分页方案（`offset`、`cursor`、`next_uri` 或 `next_path`） +1. 使用点访问表示法指定 `results` 的位置。 -在大多数偏移分页配置中包含 `step`，以确保偏移量按页面大小递增。当您的 API 为附加页面返回布尔指示符时，请使用 `has-next-page`。 +在大多数偏移分页配置中包含 `step`，以确保偏移按页面大小递增。当您的 API 返回附加页面的布尔指示器时，请使用 `has-next-page`。 @@ -441,7 +447,7 @@ types: ### 幂等端点 -将端点标记为幂等，以允许 SDK 用户指定幂等性标头进行安全的请求重试。您还必须在 [`api.yml` 中配置幂等性标头](/learn/api-definitions/ferndef/api-yml/global-headers#idempotency-headers)来定义哪些标头可用。 +将端点标记为幂等，以允许 SDK 用户为安全请求重试指定幂等性头。您还必须在 [`api.yml` 中配置幂等性头](/learn/api-definitions/ferndef/api-yml/global-headers#idempotency-headers) 来定义哪些头可用。 ```yaml title="service.yml" {8} service: @@ -458,7 +464,8 @@ service: ### 错误响应 -端点可以指定错误响应，详细说明端点可能返回的非 200 响应。 +端点可以指定错误响应，详细说明 +端点可能返回的非 200 响应。 ```yaml @@ -491,7 +498,9 @@ errors: ## 指定示例 -当您声明一个示例时，您也可以指定该端点可能如何使用的一些示例。编译器使用这些示例来增强生成的输出。示例将在您的 SDK、API 文档和 Postman 集合中显示为注释。 +当您声明一个示例时，您还可以指定一些该 +端点如何使用的示例。这些被编译器用来增强生成的 +输出。示例将在您的 SDK、API 文档和 Postman 集合中显示为注释。 您可以为端点、类型和错误添加示例。 @@ -529,7 +538,7 @@ errors: ``` -如果您要向端点添加示例，而该类型已经有示例，您可以使用 `$` 引用它。 +如果您要向端点添加示例且类型已经有示例，您可以使用 `$` 引用它。 ```yaml service: auth: true @@ -569,7 +578,7 @@ service: properties: id: type: uuid - docs: The unique identifier for the address. + docs: 地址的唯一标识符。 examples: - name: WhiteHouseWithID value: @@ -582,7 +591,8 @@ service: isResidential: true ```` -示例包含端点调用的所有信息，包括请求体、路径参数、查询参数、标头和响应体。 +示例包含有关端点调用的所有信息，包括 +请求体、路径参数、查询参数、头和响应体。 ```yaml @@ -601,7 +611,8 @@ service: #### 失败示例 -您也可以指定失败的端点调用示例。向响应示例添加 `error` 属性来指定您正在演示的失败。 +您还可以指定失败端点调用的示例。添加 `error` +属性到响应示例以指定您正在演示哪个失败。 ```yaml {5} @@ -617,7 +628,7 @@ errors: ``` -如果错误有体，那么您必须在示例中包含该体。 +如果错误有主体，则必须在示例中包含主体。 ```yaml {6, 11} @@ -637,7 +648,7 @@ errors: #### 从类型引用示例 -为了避免重复，您可以使用 `$` 从类型引用示例。 +为避免重复，您可以使用 `$` 从类型引用示例。 ```yaml {12} @@ -661,4 +672,4 @@ types: - name: Example1 value: user-id-123 ``` - \ No newline at end of file + diff --git a/fern/translations/zh/products/api-def/ferndef/endpoints/bytes.mdx b/fern/translations/zh/products/api-def/ferndef/endpoints/bytes.mdx index 444c61a9a..42703dda5 100644 --- a/fern/translations/zh/products/api-def/ferndef/endpoints/bytes.mdx +++ b/fern/translations/zh/products/api-def/ferndef/endpoints/bytes.mdx @@ -1,7 +1,7 @@ --- title: 二进制数据和文件 -subtitle: 使用 `bytes` 类型处理 API 中的二进制数据 -sidebar-title: 二进制数据和文件 +subtitle: 使用 `bytes` 类型在您的 API 中处理二进制数据 +noindex: true --- @@ -9,9 +9,9 @@ sidebar-title: 二进制数据和文件 `bytes` 类型允许您在请求和响应中处理二进制数据。 -## 发送字节数据 +## 发送字节 -如果您的 API 需要发送字节流（即通常用于音频、图像和其他文件等资源），那么您可以在 Fern Definition 中使用 `bytes` 类型来建模。 +如果您的 API 需要发送字节流（即音频、图像和其他文件等资源的典型用法），那么您可以在 Fern 定义中使用 `bytes` 类型来建模。 ```yml audio.yml service: @@ -27,13 +27,13 @@ service: docs: The bytes of the MP3 file that you would like to upload ``` -## 接收字节数据 +## 接收字节 - 在响应中处理二进制数据时，请使用 `type: file` 而不是 `type: bytes`。 + 在响应中处理二进制数据时，使用 `type: file` 而不是 `type: bytes`。 -另一方面，如果您的 API 返回字节流，那么您可以利用 `bytes` 类型作为响应。 +另一方面，如果您的 API 要返回字节流，那么您可以利用 `bytes` 类型作为响应。 ```yml textToSpeech.yml service: @@ -53,4 +53,4 @@ service: response: type: file docs: The bytes of the audio file. -``` \ No newline at end of file +``` diff --git a/fern/translations/zh/products/api-def/ferndef/endpoints/multipart.mdx b/fern/translations/zh/products/api-def/ferndef/endpoints/multipart.mdx index c3344dc9e..e83023394 100644 --- a/fern/translations/zh/products/api-def/ferndef/endpoints/multipart.mdx +++ b/fern/translations/zh/products/api-def/ferndef/endpoints/multipart.mdx @@ -1,11 +1,10 @@ --- title: 多部分文件上传 -description: 使用 `multiform` 内容类型记录端点。 -sidebar-title: 多部分文件上传 +description: 文档化具有 `multiform` 内容类型的端点。 +noindex: true --- - -在 Fern 中，端点定义在 `endpoints` 键下。如果您的端点请求包含文件上传，您可以使用 `file` 类型来指示请求是 `multiform` 内容类型。下面的示例演示了一个在请求体中包含文件的端点。 +Fern 中的端点定义在 `endpoints` 键下。如果您的端点请求包含文件上传，您可以使用 `file` 类型来指示请求是 `multiform` 内容类型。下面的示例演示了一个在请求体中包含文件的端点。 ```yaml {12} @@ -28,7 +27,7 @@ service: ## 文件列表 -如果您的端点支持文件列表，那么您的请求体必须如此指示。 +如果您的端点支持文件列表，那么您的请求体必须指明这一点。 ```yaml {12} @@ -45,4 +44,4 @@ service: properties: files: list ``` - \ No newline at end of file + diff --git a/fern/translations/zh/products/api-def/ferndef/endpoints/rest.mdx b/fern/translations/zh/products/api-def/ferndef/endpoints/rest.mdx index 9560f07d3..403f005df 100644 --- a/fern/translations/zh/products/api-def/ferndef/endpoints/rest.mdx +++ b/fern/translations/zh/products/api-def/ferndef/endpoints/rest.mdx @@ -1,11 +1,10 @@ --- title: HTTP JSON 端点 -sidebar-title: HTTP JSON 端点 -description: "在 Fern Definition 的 endpoints 键下定义 HTTP JSON 端点,包括路径、方法、请求体、响应和示例。" +noindex: true +description: "在 Fern Definition 的 endpoints 键下定义 HTTP JSON 端点，包括路径、方法、请求体、响应和示例。" --- - -Fern 中的端点定义在 `endpoints` 键下。以下是定义单个 REST 端点的示例： +端点在 Fern 中定义在 `endpoints` 键下。以下是定义单个 REST 端点的示例： ```yml title="users.yml" maxLines=0 service: @@ -23,7 +22,7 @@ service: ## 示例 -你可以通过使用 `examples` 键来提供请求和响应的示例。 +您可以通过使用 `examples` 键来提供请求和响应的示例。 ```yaml {11-17} service: @@ -43,4 +42,4 @@ service: body: userId: alice-user-id name: Alice -``` \ No newline at end of file +``` diff --git a/fern/translations/zh/products/api-def/ferndef/endpoints/sse.mdx b/fern/translations/zh/products/api-def/ferndef/endpoints/sse.mdx index 07dcfaed9..b683c2992 100644 --- a/fern/translations/zh/products/api-def/ferndef/endpoints/sse.mdx +++ b/fern/translations/zh/products/api-def/ferndef/endpoints/sse.mdx @@ -1,15 +1,14 @@ --- title: 服务器发送事件和流式 API subtitle: 使用 `response-stream` 键来建模流式端点 -sidebar-title: 服务器发送事件和流式 API +noindex: true --- - 在端点上指定 `response-stream` 允许您表示流式响应的端点。 -## JSON 流式传输 +## JSON 流 如果您的 API 返回一系列 `JSON` 块，如下所示 @@ -19,7 +18,7 @@ sidebar-title: 服务器发送事件和流式 API { "text": "questions for me"} ``` -那么只需在端点的 `response-stream` 下指定响应即可。 +那么只需在您的端点的 `response-stream` 下指定响应。 ```yaml title="chat.yml" {4} service: @@ -38,7 +37,7 @@ types: ## 服务器发送事件 -如果您的 API 返回服务器发送事件，带有 `data` 和 `event` 键，如下所示 +如果您的 API 返回服务器发送事件，包含 `data` 和 `event` 键，如下所示 ```json data: { "text": "Hi, I am a" } @@ -67,7 +66,7 @@ types: ## `Stream` 参数 -端点具有 `stream` 参数来控制响应是否流式传输已成为常见做法。Fern 以一等公民的方式支持此模式。 +对于端点来说，拥有一个 `stream` 参数来控制响应是否流式传输已经成为常见做法。Fern 以一流的方式支持这种模式。 只需指定 `stream-condition` 以及普通响应和流式响应： @@ -97,4 +96,4 @@ types: ChatChunk: properties: text: string -``` \ No newline at end of file +``` diff --git a/fern/translations/zh/products/api-def/ferndef/errors.mdx b/fern/translations/zh/products/api-def/ferndef/errors.mdx index ba16cba5c..e3c00fe75 100644 --- a/fern/translations/zh/products/api-def/ferndef/errors.mdx +++ b/fern/translations/zh/products/api-def/ferndef/errors.mdx @@ -1,15 +1,15 @@ --- title: Fern Definition 中的错误 description: 在 Fern Definition 中添加表示 API 端点失败响应的错误。 -sidebar-title: Fern Definition 中的错误 +noindex: true --- 错误表示端点的失败（非 200）响应。 -一个错误包含： +一个错误具有： - HTTP 状态码 -- 主体类型 _（可选）_ +- 响应体类型 _（可选）_ ```yaml @@ -23,4 +23,4 @@ types: properties: requestedUserId: string ``` - \ No newline at end of file + diff --git a/fern/translations/zh/products/api-def/ferndef/examples.mdx b/fern/translations/zh/products/api-def/ferndef/examples.mdx index f02496a9e..958fe87e9 100644 --- a/fern/translations/zh/products/api-def/ferndef/examples.mdx +++ b/fern/translations/zh/products/api-def/ferndef/examples.mdx @@ -1,14 +1,14 @@ --- -title: Fern 定义中的示例 -subtitle: 使用 Fern 定义添加 API 示例，这些示例会显示在 SDK 注释、API 参考文档和 Postman 集合中。 -sidebar-title: Fern 定义中的示例 +title: Fern Definition 中的示例 +subtitle: 使用 Fern Definition 添加 API 示例，这些示例将显示在 SDK 的注释、API 参考文档以及 Postman 集合中。 +noindex: true --- -您可以为类型和端点添加示例。示例会显示为 SDK 中的注释、文档的请求和响应部分，以及 Postman 集合中。 +您可以为类型和端点添加示例。示例会显示在您的 SDK 注释、文档的请求和响应以及 Postman 集合中。 ## 验证 -Fern CLI 会验证您的示例是否与预期的类型匹配。以下内容无法编译： +Fern CLI 会验证您的示例是否匹配预期的类型。以下代码将无法编译： ```yaml types: @@ -18,16 +18,16 @@ types: - value: hello # 不是整数 ``` -```bash CLI 错误消息 +```bash CLI 错误信息 [api]: example.yml -> types -> UserId -> examples[0] - 期望示例为整数。示例值为："hello" + 预期示例为整数类型。示例值为: "hello" ``` ## 引用示例 您可以引用来自其他类型、端点或错误的示例。 -就像类型一样，您可以组合示例。要引用来自其他类型的示例，请使用 `$`。 +就像类型一样，您可以组合示例。要引用来自另一个类型的示例，请使用 `$`。 ```yaml {14} types: @@ -82,12 +82,12 @@ types: isResidential: false ``` - + ```typescript /** - * 代表一个邮寄地址。 + * Represents a shipping address. * - * 白宫地址 + * The White House address * @example { * street1: "1600 Pennsylvania Avenue NW", * city: "Washington DC", @@ -97,7 +97,7 @@ types: * isResidential: true * } * - * * 帝国大厦地址 + * * The Empire State Building address * @example { * street1: "350 5th Ave", * street2: "Attn: Maintenance Department", @@ -134,9 +134,9 @@ type ShipTo = { estimatedDeliveryDate: "2024-01-13" ``` -### 联合 +### 联合类型 -#### 有区分的联合 +#### 可区分联合 ```yml types: @@ -156,12 +156,12 @@ types: likesToMeow: boolean ``` - + ```typescript /** - * 代表一个动物，可以是狗或猫。 + * Represents an animal, which can be either a Dog or a Cat. * - * 狗的示例： + * Example of a Dog: * @example { * type: "dog", * likesToWoof: true @@ -171,7 +171,7 @@ type Animal = Dog | Cat; ``` -#### 无区分的联合 +#### 不可区分联合 ```yml types: @@ -191,12 +191,12 @@ types: likesToMeow: boolean ``` - + ```typescript /** - * 代表一个动物，可以是狗或猫。 + * Represents an Animal, which can be either a Dog or a Cat. * - * 动物作为猫的示例： + * Example of an Animal as a Cat: * @example { * likesToMeow: true * } @@ -210,7 +210,7 @@ type Animal = Dog | Cat; ```yml types: UserId: - docs: 用户的唯一标识符 + docs: A unique identifier for a user type: string examples: - value: user-id-123 @@ -219,7 +219,7 @@ types: ```typescript /** - * 用户的唯一标识符 * + * A unique identifier for a user * * @example "user-id-123" */ type UserId = string; @@ -228,7 +228,8 @@ types: ## 端点示例 -您可以为端点添加成功和错误响应的示例。示例可以引用类型的示例以避免重复。 +您可以为端点添加成功和错误响应的示例。 +示例可以引用类型的示例以避免重复。 ```yml service: @@ -236,7 +237,7 @@ service: base-path: "" endpoints: CreateShippingLabel: - docs: 创建新的运输标签。 + docs: Create a new shipping label. method: POST path: /shipping request: CreateShippingLabelRequest @@ -245,7 +246,7 @@ service: - NotAuthorized - InsufficientFunds examples: - # 不引用其他示例的成功响应。 + # A successful response that doesn't reference other examples. - request: orderId: "online_789" weightInOunces: 5 @@ -256,12 +257,12 @@ service: trackingNumber: "1Z26W8370303469306" price: 2.50 - # 使用引用的成功响应。 + # A successful response that uses references. - request: $CreateShippingLabelRequest.SuccessfulRequest response: body: $ShippingLabel.Default - # 错误响应。 + # An error response. - request: $CreateShippingLabelRequest.InsufficientFundsRequest response: error: InsufficientFunds @@ -312,9 +313,9 @@ errors: type: InsufficientFundsBody ``` -### 带请求头的示例 +### 包含请求头的示例 -当您在 `api.yml` 中定义了[全局请求头](/api-definitions/ferndef/api-yml/global-headers#global-headers)时，必须在示例中包含它们： +当您在 `api.yml` 中[定义了全局请求头](/api-definitions/ferndef/api-yml/global-headers#global-headers)时，必须在示例中包含它们： ```yml {15-16} service: @@ -322,7 +323,7 @@ service: base-path: "" endpoints: CreateShippingLabel: - docs: 创建新的运输标签。 + docs: Create a new shipping label. method: POST path: /shipping request: CreateShippingLabelRequest @@ -352,7 +353,7 @@ service: base-path: "" endpoints: TrackShipment: - docs: 跟踪货物的状态。 + docs: Track the status of a shipment. method: GET path: /shipping/{trackingNumber} path-parameters: @@ -365,4 +366,4 @@ service: body: status: "InTransit" estimatedDeliveryDate: "2024-01-11" -``` \ No newline at end of file +``` diff --git a/fern/translations/zh/products/api-def/ferndef/export-openapi.mdx b/fern/translations/zh/products/api-def/ferndef/export-openapi.mdx index 3757bc618..a519b499e 100644 --- a/fern/translations/zh/products/api-def/ferndef/export-openapi.mdx +++ b/fern/translations/zh/products/api-def/ferndef/export-openapi.mdx @@ -1,14 +1,14 @@ --- title: 从 Fern Definition 导出到 OpenAPI -description: 使用 fern export 命令将 Fern Definition 导出为 OpenAPI 3.1 格式。防止供应商锁定并轻松转换您的 API 定义。 -sidebar-title: 从 Fern Definition 导出到 OpenAPI +description: 使用 fern export 命令将 Fern Definition 导出为 OpenAPI 3.1 格式。防止供应商锁定，轻松转换您的 API 定义。 +noindex: true --- -为了防止被锁定在 Fern Definition 格式中，您可以随时使用 [`fern export` 命令](/cli-api-reference/cli-reference/commands#fern-export)将您的 API 定义导出为 OpenAPI 3.1。 +为了防止锁定在 Fern Definition 格式中，您可以随时[使用 `fern export` 命令](/cli-api-reference/cli-reference/commands#fern-export)将您的 API 定义导出为 OpenAPI 3.1。 -如果您在 `fern/apis/` 文件夹中定义了多个 API，请使用 `--api` 来指定要导出的 API。 +如果您在 `fern/apis/` 文件夹中定义了多个 API，请使用 `--api` 指定要导出的 API。 - + ```bash fern export path/to/openapi.yml fern export path/to/openapi.json @@ -16,4 +16,4 @@ sidebar-title: 从 Fern Definition 导出到 OpenAPI # 指定要导出的 API fern export --api public-api path/to/openapi.yml ``` - \ No newline at end of file + diff --git a/fern/translations/zh/products/api-def/ferndef/imports.mdx b/fern/translations/zh/products/api-def/ferndef/imports.mdx index e25c468c7..98971f285 100644 --- a/fern/translations/zh/products/api-def/ferndef/imports.mdx +++ b/fern/translations/zh/products/api-def/ferndef/imports.mdx @@ -1,10 +1,11 @@ --- title: Fern 定义中的导入 -description: 使用导入功能从其他 Fern 定义文件中引用 API 类型和错误。 -sidebar-title: 导入 +description: 使用导入来引用其他 Fern 定义文件中的 API 类型和错误。 +noindex: true --- -导入功能允许您从其他文件中引用类型和错误。 + +导入允许您引用其他文件中的类型和错误。 ```yaml title="person.yml" types: @@ -17,7 +18,7 @@ imports: types: Family: properties: - people: list # 使用导入的类型 + people: list # use an imported type ``` -请注意，您只能导入存在于您的 Fern 定义中的文件（即，在同一个 `definition/` 文件夹中）。 \ No newline at end of file +请注意，您只能导入 Fern 定义中存在的文件（即，在同一个 `definition/` 文件夹中）。 diff --git a/fern/translations/zh/products/api-def/ferndef/overview.mdx b/fern/translations/zh/products/api-def/ferndef/overview.mdx index 926f06e73..29ce01b2e 100644 --- a/fern/translations/zh/products/api-def/ferndef/overview.mdx +++ b/fern/translations/zh/products/api-def/ferndef/overview.mdx @@ -1,14 +1,11 @@ --- title: 什么是 Fern Definition？ -description: Fern Definition 是用于 API 规范的 YAML 格式。在一个统一的真实数据源中定义您的 REST API 端点、数据模型和错误。 -sidebar-title: 什么是 Fern Definition？ +description: Fern Definition 是一种用于 API 规范的 YAML 格式。在一个单一源头中定义你的 REST API 端点、数据模型和错误。 +noindex: true --- -Fern Definition 是一组 YAML 文件，是您 API 的单一真实数据源。您可以将 Fern Definition 提交到您的代码库中，其中描述了您的 API 请求、响应、模型、路径、方法、错误和身份验证方案。 - - - 想要使用 OpenAPI？没问题，我们[同样支持](/learn/api-definitions/overview/what-is-an-api-definition#openapi-swagger) - +Fern Definition 是一组 YAML 文件，它们是你 API 的单一源头。你将 Fern Definition 检入到你的代码仓库中， +在其中描述你的 API 请求、响应、模型、路径、方法、错误和身份验证方案。 ## Fern Definition 结构 @@ -19,12 +16,12 @@ npm install -g fern-api fern init ``` -这将在您的项目中创建以下文件夹结构： +这将在你的项目中创建以下文件夹结构： - + @@ -36,10 +33,10 @@ fern init 每个 Fern Definition 文件可以定义： -- **[自定义类型](/learn/api-definitions/ferndef/types)**。使用**自定义类型**来构建您的数据模型。 +- **[自定义类型](/learn/api-definitions/ferndef/types)**。使用**自定义类型**来构建你的数据模型。 - **[端点](/learn/api-definitions/ferndef/endpoints/overview)**。一个**服务**是一组相关的 REST 端点。 -- **[错误](/learn/api-definitions/ferndef/errors)**。一个**错误**代表端点的失败（非 200）响应。 -- **[导入](/learn/api-definitions/ferndef/imports)**。使用**导入**在文件之间共享类型。 +- **[错误](/learn/api-definitions/ferndef/errors)**。一个**错误**表示来自端点的失败（非 200）响应。 +- **[导入](/learn/api-definitions/ferndef/imports)**。使用**导入**在文件间共享类型。 ```yml imdb.yml maxLines=0 service: @@ -92,12 +89,15 @@ errors: statusCode: 401 ``` -## 为什么要使用另一种格式？ +## 为什么需要另一种格式？ -Google 构建了 gRPC。Amazon 构建了 Smithy。Facebook 构建了 GraphQL。Palantir 构建了 Conjure。这些公司拒绝了 OpenAPI，而选择了更简洁的 API Definition Language。 +Google 构建了 gRPC。Amazon 构建了 Smithy。Facebook 构建了 GraphQL。Palantir 构建了 +Conjure。这些公司放弃了 OpenAPI，选择了更简洁的 API Definition Language。 -我们构建 Fern 是为了将这种设计产品化，并使所有软件公司都能使用它。 +我们构建 Fern 是为了将这种设计产品化，并让所有 +软件公司都能使用它。 - 尽管这是描述 API 的不同格式，**但您永远不会被锁定在 Fern 中**。将您的 [Fern Definition 转换为 OpenAPI](/learn/api-definitions/ferndef/export-openapi) 很容易。 - \ No newline at end of file + 尽管是描述 API 的不同格式，**你永远不会被锁定在 Fern 中。** 将你的 + [Fern Definition 转换为 OpenAPI](/learn/api-definitions/ferndef/export-openapi) 很容易。 + diff --git a/fern/translations/zh/products/api-def/ferndef/packages.mdx b/fern/translations/zh/products/api-def/ferndef/packages.mdx index 83dd37eda..e1313dadd 100644 --- a/fern/translations/zh/products/api-def/ferndef/packages.mdx +++ b/fern/translations/zh/products/api-def/ferndef/packages.mdx @@ -1,12 +1,13 @@ --- -title: Fern 定义中的包 -description: Fern 定义支持在包之间重用 API 类型和错误名称，并可以配置您的 API 文档结构。 -sidebar-title: 包 +title: Fern Definition 中的包 +description: Fern Definition 支持跨包重用 API 类型和错误名称，并可以配置 API 文档的结构。 +noindex: true --- + ## 什么是包？ -您的 API 定义中的每个文件夹都是一个包。 +API 定义中的每个文件夹都是一个包。 @@ -22,7 +23,7 @@ sidebar-title: 包 -生成的 SDK 将匹配您的 API 定义层次结构。 +生成的 SDK 将匹配你的 API 定义的层次结构。 ```ts @@ -38,9 +39,9 @@ client.roles.admin.get(); ## 包配置 -每个包都可以有一个名为 `__package__.yml` 的特殊定义文件。与任何其他定义文件一样，它可以包含[导入](/learn/api-definitions/ferndef/imports)、[类型](/learn/api-definitions/ferndef/types)、[端点](/learn/api-definitions/ferndef/endpoints/overview)和[错误](/learn/api-definitions/ferndef/errors)。 +每个包可以有一个名为 `__package__.yml` 的特殊定义文件。与任何其他定义文件一样，它可以包含[导入](/learn/api-definitions/ferndef/imports)、[类型](/learn/api-definitions/ferndef/types)、[端点](/learn/api-definitions/ferndef/endpoints/overview)和[错误](/learn/api-definitions/ferndef/errors)。 -`__package__.yml` 中的端点将出现在包的根目录下。 +`__package__.yml` 中的端点将出现在包的根目录。 例如，以下生成的 SDK： @@ -51,7 +52,7 @@ client.getProjects(); ``` -将具有一个 `fern/` 文件夹： +将有一个 `fern/` 文件夹： @@ -81,9 +82,9 @@ service: ## 命名空间 -每个包都有自己的命名空间。这意味着您可以在包之间重用类型名称和错误名称。 +每个包都有自己的命名空间。这意味着你可以在不同包中重用类型名称和错误名称。 -这在版本化您的 API 时很有用。例如，当您想要增加 API 版本时，可以将现有的 API 复制到新包中并开始进行更改。如果新的 API 版本重用了某些类型或错误，这是可以的，因为两个 API 位于不同的包中。 +这在对 API 进行版本控制时很有用。例如，当你想要增加 API 版本时，可以将现有 API 复制到新包中并开始进行更改。如果新的 API 版本重用了某些类型或错误，这是可以的，因为两个 API 存在于不同的包中。 @@ -105,9 +106,9 @@ service: ## 导航 -`__package__.yml` 还允许您配置服务的导航顺序。当您想要控制文档的显示时，这是相关的。 +`__package__.yml` 还允许你配置服务的导航顺序。当你想要控制文档的显示时，这很有用。 -例如，假设您有以下 `fern/` 文件夹： +例如，假设你有以下 `fern/` 文件夹： @@ -121,7 +122,7 @@ service: -您的 API 将按字母顺序排序：projects、roles，然后是 users。如果您想控制导航，可以添加一个 `__package__.yml` 文件并配置顺序： +你的 API 将按字母顺序排序：projects、roles，然后是 users。如果你想要控制导航，可以添加一个 `__package__.yml` 文件并配置顺序： @@ -143,4 +144,4 @@ navigation: - roles.yml - projects.yml ``` - \ No newline at end of file + diff --git a/fern/translations/zh/products/api-def/ferndef/types.mdx b/fern/translations/zh/products/api-def/ferndef/types.mdx index f0609c4f3..cd184f74d 100644 --- a/fern/translations/zh/products/api-def/ferndef/types.mdx +++ b/fern/translations/zh/products/api-def/ferndef/types.mdx @@ -1,10 +1,10 @@ --- -title: Fern 定义中的类型 -description: 类型描述了您的 API 的数据模型。Fern 具有许多内置类型，支持自定义类型，以及扩展和别名对象和联合类型。 -sidebar-title: 类型 +title: Fern 定义中的类型 +description: 类型描述了 API 的数据模型。Fern 提供了许多内置类型，并支持自定义类型以及对象的扩展、别名和联合类型。 +noindex: true --- -类型描述了您的 API 的数据模型。 +类型描述了 API 的数据模型。 ## 内置类型 @@ -12,24 +12,24 @@ sidebar-title: 类型 |------|-------------| | `string` | 基本字符串类型 | | `integer` | 整数类型 | -| `long` | 长整数类型 | +| `long` | 长整型 | | `double` | 双精度浮点数 | | `boolean` | 布尔值 true/false | -| `datetime` | [RFC 3339, section 5.6 datetime](https://ijmacd.github.io/rfc3339-iso8601/)。例如，`2017-07-21T17:32:28Z` | -| `date` | RFC 3339, section 5.6 日期 (YYYY-MM-DD)。例如，`2017-07-21` | +| `datetime` | [RFC 3339, section 5.6 datetime](https://ijmacd.github.io/rfc3339-iso8601/) 格式。例如：`2017-07-21T17:32:28Z` | +| `date` | RFC 3339, section 5.6 日期格式 (YYYY-MM-DD)。例如：`2017-07-21` | | `uuid` | UUID 标识符 | -| `base64` | Base64 编码数据 | -| `list` | 允许重复的有序集合，例如，`list` | -| `set` | 具有唯一元素的无序集合，例如，`set` | -| `map` | 键值映射，例如，`map` | -| `optional` | 可选值，例如，`optional` | -| `literal` | 字面值，例如，`literal<"Plants">` | -| `file` | 文件上传类型，例如，[文件上传](/learn/api-definitions/ferndef/endpoints/multipart) | +| `base64` | Base64 编码的数据 | +| `list` | 允许重复元素的有序集合，例如：`list` | +| `set` | 包含唯一元素的无序集合，例如：`set` | +| `map` | 键值映射，例如：`map` | +| `optional` | 可选值，例如：`optional` | +| `literal` | 字面值，例如：`literal<"Plants">` | +| `file` | 文件上传类型，例如：[文件上传](/learn/api-definitions/ferndef/endpoints/multipart) | | `unknown` | 表示任意 JSON | ## 自定义类型 -在 Fern 中创建您自己的类型很容易！ +在 Fern 中创建自定义类型非常简单！ ### 对象 @@ -125,7 +125,7 @@ types: - SNOWING ``` -枚举名称仅限于 `A-Z`、`a-z`、`0-9` 和 `_`，以确保生成的代码能够在 Fern 能够输出的所有语言中编译。如果您有一个不遵循此约定的枚举，您可以使用 `"name"` 键来指定自定义名称： +枚举名称仅限于 `A-Z`、`a-z`、`0-9` 和 `_`，以确保生成的代码能够在 Fern 可以输出的所有语言中编译。如果您的枚举不遵循此约定，您可以使用 `"name"` 键来指定自定义名称： ```yaml types: @@ -159,7 +159,7 @@ types: likesToMeow: boolean ``` -在 JSON 中，联合有一个**判别属性**来区分联合的不同成员。默认情况下，Fern 使用 `"type"` 作为判别属性： +在 JSON 中，联合具有**判别属性**来区分联合的不同成员。默认情况下，Fern 使用 `"type"` 作为判别属性： ```json { @@ -185,7 +185,7 @@ types: likesToMeow: boolean ``` -这对应于如下的 JSON 对象： +这对应于这样的 JSON 对象： ```json { @@ -194,9 +194,9 @@ types: } ``` -### 无判别联合 +### 非判别联合 -无判别联合类似于判别联合，但是您不需要定义显式的判别属性。 +非判别联合类似于判别联合，但是您不需要定义显式的判别属性。 ```yaml MyUnion: @@ -208,7 +208,7 @@ MyUnion: ### 泛型 -Fern 支持浅泛型对象，以最小化代码重复。您可以定义一个泛型以供重用： +Fern 支持浅层泛型对象，以最小化代码重复。您可以这样定义泛型以供重用： ```yaml MySpecialMapItem: @@ -228,7 +228,7 @@ StringStringMapItem: type: Response ``` -您现在可以像使用任何其他类型一样自由使用这种类型！请注意，生成的代码不会使用泛型。上面的示例将在 TypeScript 中生成为： +现在您可以像使用任何其他类型一样自由使用此类型！注意，生成的代码不会使用泛型。上面的示例将在 typescript 中生成为： ```typescript type StringIntegerMapItem = { @@ -244,11 +244,11 @@ type StringStringMapItem = { } ``` -### 文档化类型 +### 为类型添加文档 -您可以为类型添加文档。这些文档被传递到编译器中，在生成的输出中非常有用（例如，SDK 中的文档字符串）。 +您可以为类型添加文档。这些文档会传递给编译器，在生成的输出中非常有用（例如，SDK 中的文档字符串）。 - + ```yaml types: Person: @@ -256,19 +256,19 @@ types: properties: name: string age: - docs: 年龄（以年为单位） + docs: 年龄（年） type: integer ``` - + ```typescript /** * 一个人代表一个人类 */ interface Person { name: string; - // 年龄（以年为单位） + // 年龄（年） age: number; } ``` @@ -276,23 +276,23 @@ interface Person { ### 验证类型 -您可以向类型（别名和引用）添加验证约束以确保数据完整性。这些验证约束存在于您的 API 定义中，由服务器强制执行，但生成的客户端 SDK 不包含验证逻辑。 +您可以为类型（别名和引用）添加验证约束，以确保数据完整性。这些验证约束存在于您的 API 定义中，并由服务器强制执行，但生成的客户端 SDK 不包含验证逻辑。 - + ```yaml {8-11, 15-17} types: Person: docs: 一个人代表一个人类 properties: name: - docs: 该人的全名 + docs: 此人的全名 type: string validation: minLength: 2 maxLength: 100 pattern: "^[A-Za-z ]+$" age: - docs: 年龄（以年为单位） + docs: 年龄（年） type: integer validation: min: 0 @@ -303,7 +303,7 @@ types: -字符串类型支持几个验证约束。 +字符串类型支持多种验证约束。 ```yaml {4-6, 11-13, 16-19} types: @@ -340,14 +340,14 @@ types: - 字符串格式规范（例如，"email"、"uri"、"date-time"） + 字符串格式规范（例如："email"、"uri"、"date-time"） -数字类型（包括 `integer`、`long` 和 `double`）支持几个验证约束。 +数字类型（包括 `integer`、`long` 和 `double`）支持多种验证约束。 ```yaml {4-6, 12-15, 18-20} types: @@ -373,19 +373,19 @@ types: ``` - 最小值（默认包含） + 最小值（默认为包含） - 最大值（默认包含） + 最大值（默认为包含） - 为 true 时，最小值为独占（值必须大于 min） + 当为 true 时，最小值为排他（值必须大于最小值） - 为 true 时，最大值为独占（值必须小于 max） + 当为 true 时，最大值为排他（值必须小于最大值） @@ -393,4 +393,4 @@ types: - \ No newline at end of file + diff --git a/fern/translations/zh/products/api-def/ferndef/webhooks.mdx b/fern/translations/zh/products/api-def/ferndef/webhooks.mdx index 1e3ec2ca4..b06bc5fb3 100644 --- a/fern/translations/zh/products/api-def/ferndef/webhooks.mdx +++ b/fern/translations/zh/products/api-def/ferndef/webhooks.mdx @@ -1,15 +1,16 @@ --- -title: Fern Definition 中的 Webhooks -description: 学习如何在 Fern Definition 中定义 webhooks -sidebar-title: Fern Definition 中的 Webhooks +title: Fern 定义中的 Webhooks +description: 学习如何在 Fern 定义中定义 webhooks max-toc-depth: 3 +noindex: true --- -在 Fern 中，您可以在 API 定义中指定 webhooks。这些 webhooks 将包含在生成的 SDK 和 API 文档中。 + +在 Fern 中，您可以在 API 定义中指定 webhooks。Webhooks 将被包含在生成的 SDK 和 API 文档中。 ## Webhook 定义 -每个 webhook 定义： +每个 webhook 定义以下内容： 1. **方法**：webhook 将使用的 HTTP 方法（`GET` 或 `POST`） 2. **标头**：webhook 将发送的标头 @@ -66,7 +67,7 @@ max-toc-depth: 3 ## 生成 webhook 参考 -Fern Docs 可以从您的定义自动生成 webhook 参考文档。在您的 `docs.yml` 文件中设置此配置。 +Fern Docs 可以从您的定义自动生成 webhook 参考文档。在您的 `docs.yml` 文件中进行设置。 您的 webhook 参考可以是单个文档页面： @@ -87,7 +88,7 @@ navigation: ## SDK 签名验证 -您可以使用 `webhook-signature` 块直接在 Fern Definition 中配置 webhook 签名验证。配置后，Fern 生成 SDK 工具，允许用户验证 webhook 签名并确保事件来源于您的 API。 +您可以使用 `webhook-signature` 块直接在 Fern 定义中配置 webhook 签名验证。配置后，Fern 会生成 SDK 实用工具，允许用户验证 webhook 签名并确保事件来自您的 API。 配置可以在**文档级别**（适用于所有 webhooks）或**每个 webhook**（覆盖文档级别的默认值）设置。两个级别都接受相同的配置选项。 @@ -139,4 +140,4 @@ webhooks: ### 配置选项 - \ No newline at end of file + diff --git a/fern/translations/zh/products/api-def/ferndef/websockets.mdx b/fern/translations/zh/products/api-def/ferndef/websockets.mdx index 18257c6e1..71dbcdaa1 100644 --- a/fern/translations/zh/products/api-def/ferndef/websockets.mdx +++ b/fern/translations/zh/products/api-def/ferndef/websockets.mdx @@ -1,15 +1,15 @@ --- -title: Fern Definition 中的 WebSockets -description: 了解如何在 Fern Definition 中定义 WebSockets -sidebar-title: WebSockets +title: Fern 定义中的 WebSocket +description: 学习如何在 Fern 定义中定义 WebSocket +noindex: true --- -WebSockets 使用户能够与服务器创建连接，通过该连接可以发送双向通信。 +WebSocket 使用户能够与服务器创建连接，通过该连接可以发送双向通信。 -在 Fern 中，您可以在 API 定义中指定 WebSockets。WebSockets 将包含在生成的 SDK 和 API 文档中。 +在 Fern 中，你可以在 API 定义中指定 WebSocket。WebSocket 将包含在生成的 SDK 和 API 文档中。 ## WebSocket 定义 -每个 WebSocket 都在自己的文件中定义，通过 `channel` 对象进行描述。将您的 WebSocket 定义文件放在 `fern` 文件夹中，与其他 API 定义文件一起。 +每个 WebSocket 都在自己的文件中定义，其中由 `channel` 对象描述。将你的 WebSocket 定义文件放在 `fern` 文件夹中，与其他 API 定义文件放在一起。 @@ -26,15 +26,15 @@ WebSockets 使用户能够与服务器创建连接，通过该连接可以发送 `channel` 由以下字段定义： -- `auth`：WebSocket 的身份验证方案 +- `auth`：WebSocket 的认证方案 - `path`：WebSocket 的路径 -- `headers` _（可选）_：WebSocket 将发送的任何标头 -- `path-parameters` _（可选）_：WebSocket 路径中的任何路径参数 -- `query-parameters` _（可选）_：WebSocket 初始请求中使用的任何查询参数 -- `messages` _（可选）_：WebSocket 连接后可以发送和接收的消息模式 +- `headers` _(可选)_：WebSocket 将发送的任何标头 +- `path-parameters` _(可选)_：WebSocket 路径中的任何路径参数 +- `query-parameters` _(可选)_：WebSocket 初始请求中使用的任何查询参数 +- `messages` _(可选)_：WebSocket 连接后可以发送和接收的消息的架构 - `origin`：发送消息的实体（例如 `client` 或 `server`） - - `body`：消息的模式 -- `examples`：示例 WebSocket 连接 _（可选）_ + - `body`：消息的架构 +- `examples`：WebSocket 连接示例 _(可选)_ ### WebSocket 示例 @@ -91,10 +91,10 @@ WebSockets 使用户能够与服务器创建连接，通过该连接可以发送 ### WebSocket 参考 -Fern 为 WebSockets 渲染[独特的参考页面](/learn/docs/api-references/generate-websocket-ref)。**握手**部分概述了与服务器连接的协议，而**发送**和**接收**部分概述了客户端和服务器之间可以发送的消息模式。 +Fern 为 WebSocket 渲染一个[独特的参考页面](/learn/docs/api-references/generate-websocket-ref)。**握手**部分概述了与服务器连接的协议，而**发送**和**接收**部分概述了客户端和服务器之间可以发送的消息架构。 -用户可以直接在 API 参考中连接和使用 WebSockets（查看 Hume 的 WebSockets [这里](https://dev.hume.ai/reference/text-to-speech-tts/stream-input)）。 +用户可以直接在 API 参考中连接和使用 WebSocket（查看 Hume 的 WebSocket 之一[这里](https://dev.hume.ai/reference/text-to-speech-tts/stream-input)）。 WebSocket 参考 - \ No newline at end of file + diff --git a/fern/translations/zh/products/api-def/openapi/auth.mdx b/fern/translations/zh/products/api-def/openapi/auth.mdx index 394972b3b..d672fd2b2 100644 --- a/fern/translations/zh/products/api-def/openapi/auth.mdx +++ b/fern/translations/zh/products/api-def/openapi/auth.mdx @@ -1,19 +1,18 @@ --- title: 身份验证 -description: '为 bearer、basic、API 密钥和 OAuth 等认证方案建模。' -sidebar-title: 身份验证 +description: '对 bearer、basic、API 密钥和 OAuth 等认证方案进行建模。' --- Fern 支持两种配置身份验证的方式： -- **在您的 OpenAPI 规范中**使用 `securitySchemes` — 标准方法，使身份验证配置具有可移植性，并与其他 OpenAPI 工具兼容。 -- **在 `generators.yml` 中**使用 `auth-schemes` — 用于自定义参数名称和环境变量，覆盖规范中定义的内容，或配置 OAuth（在 OpenAPI 中不可用）。 +- **在您的 OpenAPI 规范中**使用 `securitySchemes` — 标准方法，保持认证配置的可移植性，并与其他 OpenAPI 工具兼容。 +- **在 `generators.yml` 中**使用 `auth-schemes` — 使用此方式自定义参数名称和环境变量，覆盖规范中定义的内容，或配置 OAuth（在 OpenAPI 中不可用）。 -您的身份验证配置适用于生成的 SDK 和 [API 浏览器](/learn/docs/api-references/api-explorer)。所有 SDK 都支持凭据的直接配置和环境变量。如果您在两个地方定义了相同的方案，`generators.yml` 优先。 +您的身份验证配置适用于生成的 SDK 和 [API 浏览器](/learn/docs/api-references/api-explorer)。所有 SDK 都支持凭证的直接配置和环境变量。如果您在两个地方定义了相同的方案，则以 `generators.yml` 为准。 -## 在您的规范中配置身份验证 +## 在规范中配置身份验证 -在 `components.securitySchemes` 中定义您的方案，然后使用 `security` 属性全局或按端点应用它们。 +在 `components.securitySchemes` 中定义您的方案，然后使用 `security` 属性全局应用或按端点应用。 ```yml title="openapi.yml" # 定义方案 @@ -23,7 +22,7 @@ components: type: http scheme: bearer -# 在所有端点中全局应用 +# 在所有端点全局应用 security: - BearerAuth: [] ``` @@ -89,7 +88,7 @@ components: ``` - + ```yml title="openapi.yml" components: @@ -116,15 +115,15 @@ components: ``` -`prefix` 选项自动为 API 密钥添加字符串前缀，当您的 API 期望 `"Bearer abc123"` 或 `"Token abc123"` 等格式时很有用。 +`prefix` 选项会自动在 API 密钥前添加字符串，当您的 API 需要 `"Bearer abc123"` 或 `"Token abc123"` 等格式时很有用。 -### 多种身份验证方案 +### 多种认证方案 -配置端点以支持多种身份验证方案或组合。在 `security` 部分中，多个顶级项是 OR 选项，而单个项中的方案用 AND 组合。 +配置端点以支持多种身份验证方案或组合。在 `security` 部分，多个顶级项目是 OR 选项，而单个项目内的方案通过 AND 组合。 ```yaml title="openapi.yml" components: @@ -143,22 +142,22 @@ components: paths: /plant/search/status: get: - summary: 按状态搜索植物 + summary: Search plants by status security: - - bearerAuth: [] # 选项 1：仅 Bearer 令牌 - - basicAuth: [] # 选项 2：基本身份验证和 API 密钥 + - bearerAuth: [] # 选项 1：仅 Bearer token + - basicAuth: [] # 选项 2：Basic auth 和 API key apiKey: [] ``` -在此示例中，用户可以使用 Bearer 令牌或基本身份验证和 API 密钥一起进行身份验证。 +在此示例中，用户可以使用 bearer token 进行身份验证，或者同时使用 basic auth 和 API key。 -当使用 OAuth 客户端凭据与多种方案时，确保您的 OpenAPI 规范 `security` 部分中的方案名称与 `generators.yml` 中定义的名称匹配。 +在多种方案中使用 OAuth 客户端凭证时，请确保 OpenAPI 规范的 `security` 部分中的方案名称与 `generators.yml` 中定义的名称匹配。 ## 在 `generators.yml` 中自定义或覆盖身份验证 -在 [`auth-schemes`](/learn/sdks/reference/generators-yml#auth-schemes) 中定义您的方案，然后使用 [`api.auth`](/learn/sdks/reference/generators-yml#auth) 将其作为所有端点的默认值应用： +在 [`auth-schemes`](/learn/sdks/reference/generators-yml#auth-schemes) 中定义您的方案，然后使用 [`api.auth`](/learn/sdks/reference/generators-yml#auth) 将其作为所有端点的默认值： ```yml title="generators.yml" # 定义方案 @@ -169,14 +168,14 @@ auth-schemes: name: apiKey env: PLANTSTORE_API_KEY -# 将其作为所有端点的默认值应用 +# 将其作为所有端点的默认值 api: auth: BearerAuth specs: - openapi: ./openapi.yml ``` -有关完整的配置选项，请参阅 [`auth-schemes` 参考](/learn/sdks/reference/generators-yml#auth-schemes)。您还可以为[特定 SDK](/learn/sdks/reference/generators-yml#override-api-authentication-settings) 覆盖身份验证设置。 +有关完整的配置选项，请参见 [`auth-schemes` 参考](/learn/sdks/reference/generators-yml#auth-schemes)。您还可以[为特定 SDK 覆盖身份验证设置](/learn/sdks/reference/generators-yml#override-api-authentication-settings)。 生成的 SDK 用法： @@ -218,8 +217,10 @@ auth-schemes: env: MY_CLIENT_SECRET ``` +在 `username` 或 `password` 上[设置 `omit: true`](/learn/sdks/reference/generators-yml#usernameomit-passwordomit) 以从生成的 SDK 中移除它。 + - + ```yaml title="generators.yml" auth-schemes: @@ -231,7 +232,7 @@ auth-schemes: ``` - + 此功能在[专业版和企业版计划](https://buildwithfern.com/pricing)中提供。请联系 support@buildwithfern.com 开始使用。 @@ -262,11 +263,11 @@ auth-schemes: expires-in: expires_in ``` -`endpoint` 值引用您的 OpenAPI 规范中的路径。当返回 `expires-in` 时，SDK 会在令牌过期前自动刷新令牌。 +`endpoint` 值引用您的 OpenAPI 规范中的路径。当返回 `expires-in` 时，SDK 会在 token 过期前自动刷新。 如果您的 API 使用[命名空间](/learn/api-definitions/overview/project-structure#combined-sdks-from-multiple-apis)（多个 API 规范），请在端点前加上命名空间和 `::`。例如，`"payments::POST /oauth/token"`。 - \ No newline at end of file + diff --git a/fern/translations/zh/products/api-def/openapi/extensions/availability.mdx b/fern/translations/zh/products/api-def/openapi/extensions/availability.mdx index 745f72f70..c7de6cad4 100644 --- a/fern/translations/zh/products/api-def/openapi/extensions/availability.mdx +++ b/fern/translations/zh/products/api-def/openapi/extensions/availability.mdx @@ -1,24 +1,28 @@ --- title: 可用性 headline: 可用性 (OpenAPI) -sidebar-title: 可用性 -description: 在 OpenAPI 中使用 `x-fern-availability` 标记 API 端点可用性。为端点和章节设置 beta、已弃用、稳定等状态。 +description: 使用 `x-fern-availability` 在 OpenAPI 中标记 API 端点可用性。为端点和部分设置 beta、已弃用、稳定等状态。 --- -`x-fern-availability` 扩展用于在 OpenAPI 定义中标记端点的可用性。可用性信息会传播到生成的 Fern Docs 网站中，显示为可视化标签。 +`x-fern-availability` 扩展用于在您的 OpenAPI 定义中标记端点的可用性。可用性信息会传播到生成的 Fern Docs 网站中，显示为视觉标签、SDK 和 [CLI](/learn/cli-generator/get-started/openapi-extensions#availability-badges)。 -您可以在 [`docs.yml` 文件](/learn/docs/configuration/site-level-settings)中配置 API Reference 文档中章节的 `availability`。 +您可以在 [`docs.yml` 文件](/learn/docs/configuration/site-level-settings) 中配置 API 参考文档部分的 `availability`。 ## 端点 -选项包括： +选项有： -- `beta` -- `generally-available` -- `deprecated` +| 值 | 描述 | 标签 | +| --- | --- | --- | +| `alpha` | 早期实验阶段 | `Alpha` | +| `beta` | 足够稳定供早期采用者使用 | `Beta` | +| `preview` | 功能完整但可能变更 | `Preview` | +| `generally-available` | 稳定且可用于生产环境 | `GA` | +| `deprecated` | 不再推荐用于新用途 | `Deprecated` | +| `legacy` | 已被替代但仍受支持 | `Legacy` | -下面的示例将 `POST /pet` 端点标记为 `deprecated`。 +下面的示例标记 `POST /pet` 端点为 `deprecated`。 ```yaml title="openapi.yml 中的 x-fern-availability" {4} paths: @@ -27,12 +31,12 @@ paths: x-fern-availability: deprecated ``` -渲染效果如下： +渲染效果为： - -![显示已弃用标签的 API Reference 端点截图](https://fern-image-hosting.s3.amazonaws.com/fern/x-fern-availability-example.png) + +![显示已弃用标签的 API 参考端点截图](https://fern-image-hosting.s3.amazonaws.com/fern/x-fern-availability-example.png) -## 章节 +## 部分 - \ No newline at end of file + diff --git a/fern/translations/zh/products/api-def/openapi/extensions/default.mdx b/fern/translations/zh/products/api-def/openapi/extensions/default.mdx index e35c234be..466012347 100644 --- a/fern/translations/zh/products/api-def/openapi/extensions/default.mdx +++ b/fern/translations/zh/products/api-def/openapi/extensions/default.mdx @@ -2,20 +2,17 @@ title: 默认值 headline: 默认值 (OpenAPI) description: 使用 `x-fern-default` 为生成的 SDK 中的路径、头部和查询参数设置客户端默认值。 -sidebar-title: 默认值 --- -`x-fern-default` 扩展允许您为路径、头部或查询参数指定客户端默认值，包括在 [`x-fern-global-headers`](/learn/api-definitions/openapi/extensions/global-headers) 下定义的头部。当存在时，生成的 SDK 会使参数变为可选的，并在调用方省略该参数时自动发送默认值。`x-fern-default` 支持 `string` 和 `boolean` 值；其他类型（如数字）会被忽略。 +`x-fern-default` 扩展让你可以为路径、头部或查询参数指定客户端默认值，包括在 [`x-fern-global-headers`](/learn/api-definitions/openapi/extensions/global-headers) 下定义的头部。当存在此扩展时，生成的 SDK 会使参数变为可选，并在调用方省略时自动发送默认值。`x-fern-default` 支持 `string` 和 `boolean` 值；其他类型（如数字）会被忽略。 -这对于固定 API 版本头部或区域路径参数非常有用，同时仍允许调用方覆盖该值。 +这对于固定 API 版本头部或区域路径参数非常有用，同时仍允许调用方覆盖该值。`x-fern-default` 在所有 SDK 语言中都受支持。 - - `x-fern-default` 支持 TypeScript、Python、Go、Java、C#、PHP 和 Ruby SDK。 - +Fern 使用 `x-fern-default` 而不是标准的 OpenAPI `default` 属性，因为它们具有不同的语义。schema 上的 OpenAPI `default` 描述了**服务器**在参数被省略时假设的值——它是一个文档提示，不影响客户端行为。`x-fern-default` 指示生成的 SDK 在调用方未提供值时在每个请求中**主动发送**该值，确保参数始终在网络上存在。 ## 路径参数 -在下面的示例中，当调用方未指定 `region` 时，SDK 会发送 `us-east-1`。 +在下面的示例中，当调用方未指定 `region` 时，SDK 发送 `us-east-1`。 ```yaml {9} title="openapi.yml" paths: @@ -33,7 +30,7 @@ paths: ## 头部 -在下面的示例中，当调用方未指定 `X-API-Version` 时，SDK 会发送 `2024-02-08`。 +在下面的示例中，当调用方未指定 `X-API-Version` 时，SDK 发送 `2024-02-08`。 ```yaml {8} title="openapi.yml" paths: @@ -50,7 +47,7 @@ paths: ## 查询参数 -在下面的示例中，当调用方未指定 `verbose` 时，SDK 会发送 `false`。 +在下面的示例中，当调用方未指定 `verbose` 时，SDK 发送 `false`。 ```yaml {8} title="openapi.yml" paths: @@ -67,11 +64,11 @@ paths: ## 全局头部 -在下面的示例中，当调用方未指定 `X-API-Version` 全局头部时，SDK 会发送 `2024-02-08`。 +在下面的示例中，当调用方未指定 `X-API-Version` 全局头部时，SDK 发送 `2024-02-08`。 ```yaml {4} title="openapi.yml" x-fern-global-headers: - header: X-API-Version name: version x-fern-default: "2024-02-08" -``` \ No newline at end of file +``` diff --git a/fern/translations/zh/products/api-def/openapi/extensions/method-names.mdx b/fern/translations/zh/products/api-def/openapi/extensions/method-names.mdx index b102d2922..fe52b4462 100644 --- a/fern/translations/zh/products/api-def/openapi/extensions/method-names.mdx +++ b/fern/translations/zh/products/api-def/openapi/extensions/method-names.mdx @@ -1,14 +1,13 @@ --- -title: 自定义 SDK 方法名 -headline: 自定义 SDK 方法名 (OpenAPI) +title: 自定义 SDK 方法名称 +headline: 自定义 SDK 方法名称 (OpenAPI) description: 使用 `x-fern-sdk-method-name` 和 `x-fern-sdk-group-name` 来精细调整 SDK 命名。 -sidebar-title: 自定义 SDK 方法名 --- -使用 `x-fern-sdk-group-name` 和 `x-fern-sdk-method-name` 扩展来控制端点在 SDK 中的组织方式。 +使用 `x-fern-sdk-group-name` 和 `x-fern-sdk-method-name` 扩展来控制端点在您的 [SDK](/learn/sdks/overview/introduction) 和 [CLI](/learn/cli-generator/get-started/openapi-extensions) 中的组织方式。 - - 如果没有扩展存在，Fern 使用您的操作 ID 来生成 SDK 方法名。将操作 ID 格式化为 `{tag_name}_{operation_name}`（例如：`users_get`）来自动生成像 `users.get()` 这样的方法。如果操作 ID 不以标签开头，Fern 将直接使用它作为方法名。 + + 如果没有扩展存在，Fern 使用您的 operation ID 来生成 SDK 方法名称。将 operation ID 格式化为 `{tag_name}_{operation_name}`（例如：`users_get`）以自动生成类似 `users.get()` 的方法。如果 operation ID 不以 tag 开头，Fern 会直接将其用作方法名称。 在下面的示例中，Fern 将为 `POST /users` 端点生成一个名为 `client.users.create()` 的方法。 @@ -23,7 +22,7 @@ paths: ### 顶级方法 -如果您省略 `x-fern-sdk-group-name` 扩展，生成的 SDK 方法将位于客户端的根级别，而不是嵌套在资源组下。在下面的示例中，Fern 将生成一个名为 `client.send()` 的方法： +如果您省略 `x-fern-sdk-group-name` 扩展，生成的 SDK 方法将位于客户端的根目录，而不是嵌套在资源组下。在下面的示例中，Fern 将生成一个名为 `client.send()` 的方法： ```yaml title="openapi.yaml" {4} paths: @@ -35,10 +34,10 @@ paths: ### 多级嵌套 -查看 merge.dev 如何使用嵌套组 [这里](https://github.com/merge-api/merge-node-client?tab=readme-ov-file#create-link-token)。 +查看 merge.dev 如何使用嵌套组的示例[这里](https://github.com/merge-api/merge-node-client?tab=readme-ov-file#create-link-token)。 -如果您添加多个 `x-fern-sdk-group-name` 扩展，那么生成的 SDK 将嵌套组名。生成的 SDK 方法保持组名的顺序。 +如果您添加多个 `x-fern-sdk-group-name` 扩展，那么生成的 SDK 将嵌套组名称。生成的 SDK 方法保留组名称的顺序。 在下面的示例中，Fern 将生成一个名为 `client.users.notifications.send()` 的方法： @@ -50,4 +49,4 @@ paths: - users - notifications x-fern-sdk-method-name: send -``` \ No newline at end of file +``` diff --git a/fern/translations/zh/products/api-def/openapi/extensions/pagination.mdx b/fern/translations/zh/products/api-def/openapi/extensions/pagination.mdx index 8ebeeff7a..6daf4a021 100644 --- a/fern/translations/zh/products/api-def/openapi/extensions/pagination.mdx +++ b/fern/translations/zh/products/api-def/openapi/extensions/pagination.mdx @@ -2,19 +2,18 @@ title: 分页 headline: 分页 (OpenAPI) description: 使用 x-fern-pagination 扩展为列表端点配置自动分页 -sidebar-title: 分页 --- -`x-fern-pagination` 扩展为 OpenAPI 规范中的列表端点配置自动分页。[Fern 生成的 SDK](/learn/sdks/deep-dives/auto-pagination) 提供简单的迭代器，可以自动处理分页，因此 SDK 用户可以遍历所有结果，而无需手动管理分页复杂性。 +`x-fern-pagination` 扩展为 OpenAPI 规范中的列表端点配置自动分页。[SDK](/learn/sdks/deep-dives/auto-pagination) 和 [CLI](/learn/cli-generator/get-started/openapi-extensions#pagination) 用户无需手动管理页面令牌即可获得自动分页功能。 要配置分页： -1. 使用 `x-fern-pagination` 扩展注解所需的分页端点 +1. 使用 `x-fern-pagination` 扩展注释所需的分页端点 2. 指定分页方案（`offset`、`cursor`、`next_uri` 或 `next_path`） -3. 使用点访问表示法指定 `results` 的位置 +3. 使用点访问记法指定 `results` 的位置 ```yaml title="偏移分页" {5-7} @@ -133,7 +132,7 @@ paths: -如果您的结果嵌套在响应对象中，请使用点访问表示法指定路径。例如，如果结果位于 `my_nested_object.inner_list` 中，`results` 路径将是 `$response.my_nested_object.inner_list`。 +如果结果嵌套在响应对象中，请使用点访问记法指定路径。例如，如果结果位于 `my_nested_object.inner_list` 中，则 `results` 路径为 `$response.my_nested_object.inner_list`。 ```yaml {4, 7} MyResponseObject: @@ -148,4 +147,4 @@ MyResponseObject: $ref: '#/components/schemas/Plant' ``` - \ No newline at end of file + diff --git a/fern/translations/zh/products/api-def/openapi/overlays.mdx b/fern/translations/zh/products/api-def/openapi/overlays.mdx index 4bcae0386..9b775fc2e 100644 --- a/fern/translations/zh/products/api-def/openapi/overlays.mdx +++ b/fern/translations/zh/products/api-def/openapi/overlays.mdx @@ -1,27 +1,26 @@ --- -title: Overlays -description: 使用 OpenAPI Overlay 规范来自定义您的 OpenAPI 定义，而无需修改原始规范。 -sidebar-title: Overlays +title: 叠加层 +description: 使用 OpenAPI 叠加层规范来自定义您的 OpenAPI 定义，而无需修改原始规范。 --- -Overlays 让您可以自定义 OpenAPI 规范而无需修改原始文件。这在以下情况下很有用： +叠加层允许您在不修改原始文件的情况下自定义 OpenAPI 规范。这在以下情况下很有用： - 您的 API 规范是从服务器代码自动生成的 -- 您需要为 SDK 和文档配置不同的设置 +- 您需要为 SDK、文档或[生成的 CLI](/learn/cli-generator/get-started/customization#overrides-and-overlays) 配置不同的设置 - 您想要添加 Fern 配置，如分页或 SDK 方法名称 - 您想要使用 JSONPath 通配符对多个端点进行批量更改 -Overlays 遵循 [OpenAPI Overlay 规范](https://spec.openapis.org/overlay/v1.0.0.html)，并且在 OpenAPI 生态系统中是可移植的。 +叠加层遵循 [OpenAPI 叠加层规范](https://spec.openapis.org/overlay/v1.0.0.html) 并在 OpenAPI 生态系统中可移植。 - Fern 建议对 OpenAPI 规范使用 overlays 而不是 overrides。 + Fern 推荐对 OpenAPI 规范使用叠加层而非覆盖。 - [Overrides](/learn/api-definitions/openapi/overrides) 也完全受支持。如果 overrides 对您的团队有效，则无需切换。您也可以同时使用两者（先应用 overrides，然后应用 overlays）。 + [覆盖](/learn/api-definitions/openapi/overrides) 也完全受支持。如果覆盖对您的团队有效，则无需切换。您也可以同时使用两者（先应用覆盖，再应用叠加层）。 -## 配置 overlays +## 配置叠加层 -要使用 overlays，请在与您的规范相同的文件夹中创建一个 `overlays` 文件，并在 `generators.yml` 中引用它： +要使用叠加层，请在规范文件所在的文件夹中创建 `overlays` 文件，并在 `generators.yml` 中引用它： ```yaml title="generators.yml" api: @@ -30,18 +29,18 @@ api: overlays: overlays.yml ``` -## 定义 overlays 文件 +## 定义叠加层文件 -overlay 中的每个动作使用 [JSONPath](https://datatracker.ietf.org/doc/html/rfc9535) 定位元素，并应用 `update` 或 `remove` 操作： +叠加层中的每个操作使用 [JSONPath](https://datatracker.ietf.org/doc/html/rfc9535) 定位元素，并应用 `update` 或 `remove` 操作： ```yaml title="openapi-overlays.yml" -overlay: 1.0.0 # 必需：Overlay 规范版本 +overlay: 1.0.0 # 必需：叠加层规范版本 info: - title: 自定义植物商店 API # 必需：overlay 目的的可读描述 - version: 1.0.0 # 必需：用于跟踪此 overlay 更改的版本标识符 -actions: # 必需：要应用的更改的有序列表 + title: Customize Plant Store API # 必需：叠加层用途的人类可读描述 + version: 1.0.0 # 必需：用于跟踪此叠加层更改的版本标识符 +actions: # 必需：要应用的有序更改列表 - target: $.info # 选择要修改的元素的 JSONPath 表达式 - update: # 要与目标元素合并的属性 + update: # 与目标元素合并的属性 x-fern-sdk-group-name: plants - target: $.paths['/plants/{plantId}'].get.parameters[?(@.name == 'plantId')] update: @@ -49,7 +48,7 @@ actions: # 必需：要应用的更改的有序列表 ``` -Fern 要求在 JSONPath 筛选表达式周围使用括号。请使用 `[?(@.name == 'plantId')]` 而不是 `[?@.name == 'plantId']`。 +Fern 要求在 JSONPath 过滤器表达式周围使用括号。使用 `[?(@.name == 'plantId')]` 而不是 `[?@.name == 'plantId']`。 @@ -60,13 +59,13 @@ Fern 要求在 JSONPath 筛选表达式周围使用括号。请使用 `[?(@.name ```yaml title="openapi-overlays.yml" overlay: 1.0.0 info: - title: 改进 API 文档 + title: Improve API documentation version: 1.0.0 actions: - target: $.paths['/plants'].get update: - summary: 列出所有可用植物 - description: 返回商店库存中植物的分页列表。 + summary: List all available plants + description: Returns a paginated list of plants in the store inventory. ``` @@ -77,7 +76,7 @@ actions: ```yaml title="openapi-overlays.yml" overlay: 1.0.0 info: - title: 添加 Fern SDK 自定义 + title: Add Fern SDK customizations version: 1.0.0 actions: # 添加 SDK 组和方法名称 @@ -98,41 +97,41 @@ actions: -使用 `remove: true` 从您的规范中删除元素： +使用 `remove: true` 从规范中删除元素： ```yaml title="openapi-overlays.yml" {8} overlay: 1.0.0 info: - title: 移除内部端点 + title: Remove internal endpoints version: 1.0.0 actions: - target: $.paths['/internal/debug'] - description: 从公共 SDK 中移除调试端点 + description: Remove debug endpoint from public SDK remove: true ``` -## 跨 API 管理 overlays +## 跨 API 管理叠加层 -`generators.yml` 中的每个规范接受一个 overlay 文件。您可以在规范中引用相同的文件，或为不同的配置使用单独的文件。 +`generators.yml` 中的每个规范接受一个叠加层文件。您可以在多个规范中引用同一个文件，或为不同的配置使用单独的文件。 - + -当多个规范需要相同的自定义时，将它们指向同一个 overlay 文件以避免重复： +当多个规范需要相同的自定义时，将它们指向同一个叠加层文件以避免重复： ```yaml title="generators.yml" api: specs: - openapi: ./payments-api.yml - overlays: shared-overlays.yml # 两个规范使用相同的 overlay + overlays: shared-overlays.yml # 两个规范使用相同的叠加层 - openapi: ./users-api.yml overlays: shared-overlays.yml ``` -如果每个规范需要唯一的自定义，请为每个规范创建单独的 overlay 文件： +如果每个规范需要独特的自定义，请为每个规范创建单独的叠加层文件： ```yaml title="generators.yml" api: @@ -144,9 +143,9 @@ api: ``` - + -通过创建具有自己的 `generators.yml` 的单独文件夹，为 SDK 生成和文档使用不同的 overlay 文件： +通过创建各自包含 `generators.yml` 的单独文件夹，为 SDK 生成与文档使用不同的叠加层文件： @@ -171,9 +170,9 @@ api: ``` - + -为生产环境与内部 API 配置不同的 overlays： +为生产环境与内部 API 配置不同的叠加层： ```yaml title="generators.yml" {5, 11} groups: @@ -192,4 +191,4 @@ groups: ``` - \ No newline at end of file + diff --git a/fern/translations/zh/products/api-def/pages/overrides.mdx b/fern/translations/zh/products/api-def/pages/overrides.mdx index be985c1b2..0c75bb88b 100644 --- a/fern/translations/zh/products/api-def/pages/overrides.mdx +++ b/fern/translations/zh/products/api-def/pages/overrides.mdx @@ -1,28 +1,27 @@ --- -title: 覆盖 -description: 使用单独的覆盖文件自定义您的 API 定义。 -sidebar-title: 覆盖 +title: 重写 +description: 使用单独的重写文件自定义您的 API 定义。 --- -使用覆盖文件可以在不修改原始规范的情况下自定义您的 OpenAPI、AsyncAPI 或 OpenRPC 定义。这在以下情况下很有用： +使用重写文件来自定义您的 OpenAPI、AsyncAPI 或 OpenRPC 定义，而无需修改原始规范。这在以下情况下很有用： * 您的 API 规范是从服务器代码自动生成的 -* 您需要为 SDK 和文档配置不同的设置 +* 您需要为 SDK、文档或[生成的 CLI](/learn/cli-generator/get-started/customization#overrides-and-overlays) 使用不同的配置 -覆盖功能适用于 OpenAPI、AsyncAPI 和 OpenRPC 规范。对于 [Fern Definition](/api-definitions/ferndef/overview) 不需要覆盖，因为您可以直接编辑这些文件。 +重写功能适用于 OpenAPI、AsyncAPI 和 OpenRPC 规范。 - 对于 OpenAPI 规范，Fern 建议使用 [叠加层](/learn/api-definitions/openapi/overlays) 而不是覆盖。叠加层遵循官方 [OpenAPI 叠加层规范](https://spec.openapis.org/overlay/v1.0.0.html)，支持使用 JSONPath 通配符进行批量更改，并且在 OpenAPI 生态系统中具有可移植性。 + 对于 OpenAPI 规范，Fern 推荐使用[覆盖层](/learn/api-definitions/openapi/overlays)而不是重写。覆盖层遵循官方的 [OpenAPI Overlay 规范](https://spec.openapis.org/overlay/v1.0.0.html)，支持使用 JSONPath 通配符进行批量更改，并且在 OpenAPI 生态系统中是可移植的。 - 覆盖功能也完全受支持。如果覆盖对您的团队有效，则无需切换。您也可以同时使用两者（首先应用覆盖，然后应用叠加层）。 + 重写功能也完全受支持。如果重写对您的团队有效，则无需切换。您也可以同时使用两者（先应用重写，然后应用覆盖层）。 -## 实现覆盖 +## 实现重写 - + -在包含您的 API 定义的文件夹中[创建一个 `overrides.yml` 文件](/cli-api-reference/cli-reference/commands#fern-write-overrides)： +在包含您的 API 定义的文件夹中[创建 `overrides.yml` 文件](/cli-api-reference/cli-reference/commands#fern-write-overrides)： ```bash {6} fern/ @@ -33,12 +32,12 @@ fern/ └─ overrides.yml ``` - 覆盖文件的格式独立于规范。例如，即使您的 OpenAPI 规范是 JSON 格式，您也可以用 yaml 编写覆盖。 + 重写文件的格式独立于规范。例如，即使您的 OpenAPI 规范是 JSON 格式，您也可以用 yaml 格式编写重写文件。 -对于 OpenAPI、AsyncAPI 和 OpenRPC，您可以使用 [Fern 的扩展](/learn/api-definitions/asyncapi/overrides#definition-specific-extensions) 来应用自定义。 +对于 OpenAPI、AsyncAPI 和 OpenRPC，您可以使用 [Fern 的扩展](/learn/api-definitions/asyncapi/overrides#definition-specific-extensions)来应用自定义。 ```yml title="overrides.yml" {4-5} paths: @@ -58,11 +57,11 @@ api: overrides: ./overrides.yml ``` -您也可以指定[多个覆盖文件](#managing-overrides-across-apis)。 +您也可以指定[多个重写文件](#managing-overrides-across-apis)。 - -现在当您运行 `fern generate` 时，Fern 会将您的原始 API 规范与覆盖文件合并： + +现在当您运行 `fern generate` 时，Fern 会将您的原始 API 规范与重写文件组合： ```yml openapi.yml @@ -84,7 +83,7 @@ paths: x-fern-sdk-group-name: users x-fern-sdk-method-name: create ``` -```yml title="合并后" {4-5} +```yml title="combined" {4-5} paths: /users/post: post: @@ -102,32 +101,32 @@ paths: -## 跨 API 管理覆盖 +## 跨 API 管理重写 -`overrides` 字段接受单个路径或路径列表。当提供多个路径时，覆盖会按顺序依次应用，后面的文件对于冲突键会优先于前面的文件。 +`overrides` 字段接受单个路径或路径列表。当提供多个路径时，重写按顺序依次应用，对于冲突的键，后面的文件优先于前面的文件。 - + -当您的项目有多个需要相同基础覆盖的规范时，使用共享基础文件并在其上分层应用特定规范的覆盖。这避免了在每个规范中重复常见的覆盖（例如，SDK 方法名称或身份验证扩展）： +当您的项目有多个规范需要相同的基础重写时，使用共享基础文件并在其上层叠特定于规范的重写。这避免了在每个规范中重复常见重写（例如，SDK 方法名称或认证扩展）： ```yaml title="generators.yml" api: specs: - openapi: ./payments-api.yml overrides: - - ./shared-overrides.yml # 所有规范的通用覆盖 - - ./payments-overrides.yml # 支付特定的覆盖 + - ./shared-overrides.yml # 所有规范的通用重写 + - ./payments-overrides.yml # 支付特定的重写 - openapi: ./users-api.yml overrides: - - ./shared-overrides.yml # 相同的通用覆盖 - - ./users-overrides.yml # 用户特定的覆盖 + - ./shared-overrides.yml # 相同的通用重写 + - ./users-overrides.yml # 用户特定的重写 ``` - + -当您需要为 SDK 生成和文档使用完全不同的覆盖时，使用带有各自 `generators.yml` 的单独文件夹。每个文件夹只引用与其关注点相关的覆盖： +当您需要为 SDK 生成和文档使用完全不同的重写时，使用带有自己的 `generators.yml` 的单独文件夹。每个文件夹只引用与其关注点相关的重写： @@ -151,21 +150,21 @@ api: overrides: sdk-overrides.yml ``` -如果 SDK 和文档覆盖共享一个通用基础，您可以在每个文件夹内使用多个覆盖文件来避免重复： +如果 SDK 和文档重写共享一个公共基础，您可以在每个文件夹中使用多个重写文件以避免重复： ```yaml title="sdks/generators.yml" api: specs: - openapi: ../openapi.yml overrides: - - ../shared-overrides.yml # SDK 和文档的通用覆盖 - - sdk-overrides.yml # SDK 特定的覆盖 + - ../shared-overrides.yml # SDK 和文档的通用重写 + - sdk-overrides.yml # SDK 特定的重写 ``` - + -当您的公共和内部 API 共享相同的规范但需要不同的覆盖时，使用多个覆盖文件在公共基础上分层添加内部特定的内容。这在内部 API 是公共 API 超集时特别有用： +当您的公共和内部 API 共享相同的规范但需要不同的重写时，使用多个重写文件在公共基础上层叠内部特定的添加。这在内部 API 是公共 API 的超集时特别有用： ```yaml title="generators.yml" {5, 12-13} groups: @@ -179,13 +178,13 @@ groups: specs: - openapi: openapi.yml overrides: - - public-overrides.yml # 基础：所有公共覆盖 - - internal-overrides.yml # 附加：仅内部覆盖 + - public-overrides.yml # 基础：所有公共重写 + - internal-overrides.yml # 附加：仅内部重写 generators: ... ``` -这避免了在内部配置中重复公共覆盖。`internal-overrides.yml` 文件只需包含内部 API 特定的添加内容。 +这避免了在内部配置中重复公共重写。`internal-overrides.yml` 文件只需要包含特定于内部 API 的添加。 - \ No newline at end of file + diff --git a/fern/translations/zh/products/api-def/pages/project-structure.mdx b/fern/translations/zh/products/api-def/pages/project-structure.mdx index 8b9908bd9..951b1ce4a 100644 --- a/fern/translations/zh/products/api-def/pages/project-structure.mdx +++ b/fern/translations/zh/products/api-def/pages/project-structure.mdx @@ -1,22 +1,22 @@ --- title: 项目结构 description: 描述 Fern 文件夹结构 -sidebar-title: 项目结构 --- -配置 fern 从 `fern` 文件夹开始，该文件夹包含你的 API 定义、SDK 生成器和你的 CLI 版本。 -Fern 推荐使用多仓库结构，将你的 fern 文件夹放在源代码仓库中（包含你的 API 定义和生成配置），并[将每个生成的 SDK 放在其自己单独的仓库中](/sdks/overview/project-structure)。 +配置 fern 从 `fern` 文件夹开始，该文件夹包含您的 API 定义、SDK 生成器和 CLI 版本。 + +Fern 推荐使用多仓库结构，将您的 fern 文件夹放在源代码仓库中（包含您的 API 定义和生成配置），并[将每个生成的 SDK 放在各自独立的仓库中](/sdks/overview/project-structure)。 ## 目录结构 -当你运行 `fern init`（对于 Fern Definition）或 `fern init --spec-type path/to/spec`（对于其他规范）时，你的 fern 文件夹将使用以下文件进行初始化： +当您运行 `fern init --spec-type path/to/spec` 时，您的 fern 文件夹将使用以下文件进行初始化： - + @@ -25,12 +25,12 @@ Fern 推荐使用多仓库结构，将你的 fern 文件夹放在源代码仓库 ## 核心配置文件 - 除了核心文件之外，你可以选择使用 [overlays (OpenAPI)](/learn/api-definitions/openapi/overlays) 或 [overrides](/learn/api-definitions/asyncapi/overrides) 文件来自定义你的 API 定义，而无需修改原始规范。 + 除了核心文件外，您还可以选择使用[覆盖层 (OpenAPI)](/learn/api-definitions/openapi/overlays) 或[重写](/learn/api-definitions/asyncapi/overrides)文件来自定义您的 API 定义，而无需修改原始规范。 ### `fern.config.json` -`fern.config.json` 文件存储你的组织名称和 Fern CLI 版本。固定版本可以提供确定性构建。 +`fern.config.json` 文件存储您的组织名称和 Fern CLI 版本。固定版本可提供确定性构建。 ```json title="fern.config.json" { @@ -40,12 +40,12 @@ Fern 推荐使用多仓库结构，将你的 fern 文件夹放在源代码仓库 ``` - 当使用本地安装的 CLI 时，将 `version` 设置为 `"*"`。详细信息请参见[本地安装 Fern CLI](/cli-api-reference/cli-reference/overview#install-fern-cli-locally)。 + 使用本地安装的 CLI 时，将 `version` 设置为 `"*"`。有关详细信息，请参阅[本地安装 Fern CLI](/cli-api-reference/cli-reference/overview#install-fern-cli-locally)。 ### `generators.yml` -对于 OpenAPI/AsyncAPI，`generators.yml` 文件是必需的，用于声明你的 API 规范位置。这还启用了 [API 参考文档](/learn/docs/api-references/overview)。 +`generators.yml` 文件声明您的 API 规范位置。这还启用了[API 参考文档](/learn/docs/api-references/overview)。 ```yaml title="generators.yml" api: @@ -53,38 +53,34 @@ api: - openapi: ./openapi/openapi.yml ``` -**对于 Fern Definition**，不需要 `generators.yml` 来[生成 API 参考文档](/learn/docs/api-references/overview)。Fern 通过检查 `definition/` 目录自动检测你的 API。 - -对于 SDK 生成，所有规范格式都需要 `generators.yml`。添加 `groups` 部分来配置要生成哪些 SDK。详细信息请参见 [SDKs 项目结构](/sdks/overview/project-structure#generatorsyml)。 +对于 SDK 生成，需要 `generators.yml` 文件。添加 `groups` 部分来配置要生成哪些 SDK。有关详细信息，请参阅 [SDK 项目结构](/sdks/overview/project-structure#generatorsyml)。 ### API 定义文件 -对于 Fern Definition，你的 API 配置分为两个文件：`api.yml` 用于 API 范围的配置，单独的 `.yml` 文件用于你的实际端点和类型定义。有关更多信息，请参见[什么是 Fern Definition？](/api-definitions/ferndef/overview)。 +对于 [OpenAPI](/api-definitions/openapi/overview)、[AsyncAPI](/api-definitions/asyncapi/overview)、[OpenRPC](/api-definitions/openrpc/overview) 和 [gRPC](/api-definitions/grpc/overview)，您将有一个自包含的规范文件。 -对于其他规范格式（[OpenAPI](/api-definitions/openapi/overview)、[AsyncAPI](/api-definitions/asyncapi/overview)、[OpenRPC](/api-definitions/openrpc/overview) 和 [gRPC](/api-definitions/grpc/overview)），你将拥有一个独立的规范文件。 +## 在何处存储您的 API 定义 -## 存储 API 定义的位置 +管理 API 定义有三种常见方式： -有三种常见的管理 API 定义的方式： - -- **直接提交到你的 Fern 仓库（推荐）。** 将你的 API 定义文件检入包含你的 Fern 配置的同一个仓库中。如果你不在其他地方维护定义，这是最简单的方法。 -- **从源代码仓库同步。** 将你的 API 定义存储在与你的 API 源代码相同的仓库中，并将更新同步到你的 Fern 仓库。你可以使用 [`fern api update`](/cli-api-reference/cli-reference/commands#fern-api-update) CLI 命令或 [sync-openapi GitHub Action](/learn/api-definitions/openapi/sync-your-open-api-specification) 来自动化这个过程。 -- **在公共 URL 托管。** 从可公开访问的端点提供定义，并在 `generators.yml` 中配置 [`origin`](/learn/sdks/reference/generators-yml#openapi) 字段，以便 Fern 可以获取它。当你希望有一个多个消费者可以引用的单一规范定义时，这很有用。 +- **直接提交到您的 Fern 仓库（推荐）。** 将您的 API 定义文件检入包含 Fern 配置的同一仓库。如果您不在其他地方维护定义，这是最简单的方法。 +- **从源代码仓库同步。** 将您的 API 定义存储在与 API 源代码相同的仓库中，并将更新同步到您的 Fern 仓库。您可以使用 [`fern api update`](/cli-api-reference/cli-reference/commands#fern-api-update) CLI 命令或 [sync-openapi GitHub Action](/learn/api-definitions/openapi/sync-your-open-api-specification) 来自动化此过程。 +- **在公共 URL 托管。** 从可公开访问的端点提供定义，并在 `generators.yml` 中配置 [`origin`](/learn/sdks/reference/generators-yml#openapi) 字段，以便 Fern 可以获取它。当您希望有一个多个消费者可以引用的单一权威定义时，这很有用。 ## 多个 API -Fern 支持两种处理多个 API 定义的方法。两种方法都需要一个 `apis` 文件夹 — 这个文件夹必须使用这个确切的名称。 +Fern 支持处理多个 API 定义的两种方法。两种方法都需要一个 `apis` 文件夹——此文件夹必须使用确切的名称。 -1. **为每个 API 生成单独的 SDK** - 每个 API 生成自己独立的 SDK 包集合（例如，`@company/user-api`、`@company/payments-api` 或版本化的如 `@company/sdk-v1`、`@company/sdk-v2`） -2. **从多个 API 合并 SDK** - 多个 API 合并到一个 SDK 包中，并可选择使用命名空间（例如，`client.users`、`client.payments` 或版本化的如 `client.v1`、`client.v2`） +1. **为每个 API 生成独立的 SDK** - 每个 API 生成自己独立的 SDK 包集合（例如，`@company/user-api`、`@company/payments-api` 或版本化的如 `@company/sdk-v1`、`@company/sdk-v2`） +2. **从多个 API 合并 SDK** - 多个 API 合并到单个 SDK 包中，可选择命名空间（例如，`client.users`、`client.payments` 或版本化的如 `client.v1`、`client.v2`） -### 为每个 API 生成单独的 SDK +### 为每个 API 生成独立的 SDK -当每个 API 应该生成自己独立的 SDK 集合时使用这种方法。这适用于不同的 API（例如，`user-api` 和 `payments-api`）和版本化 API，你希望每个版本都可以独立安装（例如，`@company/sdk-v1`、`@company/sdk-v2`）。 +当每个 API 应该生成自己独立的 SDK 集合时使用此方法。这适用于不同的 API（例如，`user-api` 和 `payments-api`）和版本化 API，其中您希望每个版本都可以独立安装（例如，`@company/sdk-v1`、`@company/sdk-v2`）。 -将每个 API 或 API 版本放入 `fern/apis/` 的单独子文件夹中： +将每个 API 或 API 版本放入 `fern/apis/` 的独立子文件夹中： @@ -124,7 +120,7 @@ Fern 支持两种处理多个 API 定义的方法。两种方法都需要一个 -每个 API 目录包含自己的 `generators.yml` 文件，引用同一文件夹中的规范： +每个 API 目录包含自己的 `generators.yml` 文件，该文件引用同一文件夹中的规范： ```yaml title="generators.yml" api: @@ -138,17 +134,17 @@ groups: ### 从多个 API 合并 SDK - - 此功能仅适用于 [Pro 和企业版计划](https://buildwithfern.com/pricing)。在 Pro 计划中，你可以将最多五个 API 合并到单个 SDK 中，在企业版计划中可以合并无限个 API。要开始使用，请联系 support@buildwithfern.com。 + + 此功能仅适用于 [Pro 和 Enterprise 计划](https://buildwithfern.com/pricing)。您可以在 Pro 计划中将多达五个 API 合并到单个 SDK 中，在 Enterprise 计划中可以合并无限数量的 API。要开始使用，请联系 support@buildwithfern.com。 -当你想要将多个 API 合并到单个 SDK 包中，并可选择使用命名空间来组织它们时，使用这种方法。这适用于不同的 API 和版本化 API，但会增加包大小，因为所有 API 都捆绑在一起。 +当您希望将多个 API 合并到单个 SDK 包中，并可选择使用命名空间来组织它们时，请使用此方法。这适用于不同的 API 和版本化 API，但会增加包大小，因为所有 API 都打包在一起。 -对于版本化 API，命名空间让你可以在同一个包中访问不同版本，如 `client.v1` 和 `client.v2`。 +对于版本化 API，命名空间让您可以在同一包中访问不同版本，如 `client.v1` 和 `client.v2`。 - -将每个 API 放入 `fern/apis/` 的单独子文件夹中： + +将每个 API 放入 `fern/apis/` 的独立子文件夹中： @@ -200,7 +196,7 @@ groups: -添加 [`namespace`](/learn/sdks/reference/generators-yml#namespace) 来处理 API 之间重叠的模式名称或组织不同的 API 版本： +添加 [`namespace`](/learn/sdks/reference/generators-yml#namespace) 来处理 API 之间重叠的架构名称或组织不同的 API 版本： @@ -230,4 +226,4 @@ groups: - \ No newline at end of file + diff --git a/fern/translations/zh/products/api-def/pages/what-is-an-api-definition.mdx b/fern/translations/zh/products/api-def/pages/what-is-an-api-definition.mdx index 64c8066fe..1d1240957 100644 --- a/fern/translations/zh/products/api-def/pages/what-is-an-api-definition.mdx +++ b/fern/translations/zh/products/api-def/pages/what-is-an-api-definition.mdx @@ -1,21 +1,20 @@ --- title: 什么是 API 定义？ -description: 描述 API 提供方和 API 消费者之间的契约 -sidebar-title: 什么是 API 定义？ +description: 描述 API 提供者和 API 消费者之间的契约 --- - -API 定义是对您的 API 结构的机器可读规范，包括**端点**、**请求和响应模式**，以及**身份验证**要求。API 定义能够自动生成这些工件，而不需要手动保持 SDK 和文档与 API 变更的同步。 +API 定义是对你的 API 结构的机器可读规范，包括**端点**、**请求和响应模式**以及**身份验证**要求。API 定义能够自动生成这些制品，无需手动保持 SDK 和文档与 API 变更的同步。 Fern 集成了多种 API 定义格式： - OpenAPI 原称 Swagger，是最受欢迎的 API 定义格式。[OpenAPI](https://swagger.io/specification/) 可用于记录 RESTful API，并在 YAML 或 JSON 文件中定义。 + 原名为 Swagger，[OpenAPI](https://swagger.io/specification/) 是最流行的 API 定义格式。 + OpenAPI 可用于记录 RESTful API，并在 YAML 或 JSON 文件中定义。 - 在[此处](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml)查看 Petstore API 的 OpenAPI 规范示例 + 查看 Petstore API 的 OpenAPI 规范示例[这里](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml) ```yaml maxLines={0} openapi: 3.0.2 @@ -100,9 +99,9 @@ Fern 集成了多种 API 定义格式： ``` - [AsyncAPI](https://v2.asyncapi.com/docs) 是用于定义事件驱动 API 的规范。它用于记录使用 WebSocket、MQTT 和其他消息传递协议的 API。 + [AsyncAPI](https://v2.asyncapi.com/docs) 是用于定义事件驱动 API 的规范。它用于记录使用 WebSockets、MQTT 和其他消息传递协议的 API。 查看下面聊天应用程序的 AsyncAPI 规范示例： @@ -153,9 +152,9 @@ Fern 集成了多种 API 定义格式： - [OpenRPC](https://open-rpc.org/) 是用于描述 JSON-RPC 2.0 API 的规范。它为 JSON-RPC 生态系统提供了交互式文档和代码生成工具。 + [OpenRPC](https://open-rpc.org/) 是用于描述 JSON-RPC 2.0 API 的规范。它为 JSON-RPC 生态系统提供交互式文档和代码生成工具。 查看下面加密钱包服务的 OpenRPC 规范示例： @@ -194,10 +193,10 @@ Fern 集成了多种 API 定义格式： value: 42.5 ``` - - [gRPC](https://grpc.io/) 是由 Google 开发的现代开源 RPC 框架。它使用 Protocol Buffers 作为接口定义语言，支持多种编程语言，并具有高效的二进制序列化功能。 + + [gRPC](https://grpc.io/) 是由 Google 开发的现代开源 RPC 框架。它使用 Protocol Buffers 作为接口定义语言，支持多种编程语言和高效的二进制序列化。 - gRPC API 使用 Protocol Buffer（.proto）文件定义，这些文件指定服务和消息类型。查看下面的 gRPC 服务定义示例： + gRPC API 使用 Protocol Buffer (.proto) 文件定义，这些文件指定服务和消息类型。查看下面的 gRPC 服务定义示例： ```proto maxLines={0} syntax = "proto3"; @@ -260,66 +259,11 @@ Fern 集成了多种 API 定义格式： } ``` - - Fern Definition 是我们对更简单 API 定义格式的理解。它采用**最佳实践**设计，同时支持 **RESTful 和事件驱动 API**，并针对 **SDK 生成**进行了优化。 - - - Fern Definition 受到了 [Amazon](https://smithy.io/2.0/index.html)、[Google](https://grpc.io/)、[Palantir](https://blog.palantir.com/introducing-conjure-palantirs-toolchain-for-http-json-apis-2175ec172d32)、Twilio 和 Stripe 等公司内部 API Definition 格式的启发。这些公司**拒绝了** OpenAPI 并构建了自己的版本。 - - - 查看下面的 Fern Definition 示例： - - ```yaml maxLines={0} - types: - MovieId: string - - Movie: - properties: - id: MovieId - title: string - rating: - type: double - docs: The rating scale is one to five stars - - CreateMovieRequest: - properties: - title: string - rating: double - - service: - auth: false - base-path: /movies - endpoints: - createMovie: - docs: Add a movie to the database - method: POST - path: /create-movie - request: CreateMovieRequest - response: MovieId - - getMovie: - method: GET - path: /{movieId} - path-parameters: - movieId: MovieId - response: Movie - errors: - - MovieDoesNotExistError - - errors: - MovieDoesNotExistError: - status-code: 404 - type: MovieId - ``` - - - + ## 为什么要创建 API 定义？ -一旦您拥有 API 定义，Fern 就会将其用作输入来生成诸如 SDK 和 API 参考文档等工件。每当您更新 API 定义时，都可以重新生成这些工件以确保它们始终保持最新状态。 +一旦你有了 API 定义，Fern 就会将其作为输入来生成制品，如 SDK 和 API 参考文档。每次更新 API 定义时，你都可以重新生成这些制品，确保它们始终保持最新状态。 - 多语言客户端库，自动与您的 API 保持同步。 + 多种语言的客户端库，自动与你的 API 保持同步。 - 具有代码示例和实时测试功能的交互式 API 文档。 + 包含代码示例和实时测试功能的交互式 API 文档。 } href="/docs/integrations/postman" > 预填充示例请求和响应的即用型集合。 } href="/api-definitions/openapi/frameworks/fastapi" > - 用于 FastAPI 的 Pydantic 模型或用于 Spring Boot 应用程序的控制器。 + 适用于 FastAPI 的 Pydantic 模型或 Spring Boot 应用程序的控制器。 - \ No newline at end of file + diff --git a/fern/translations/zh/products/cli-api-reference/pages/commands.mdx b/fern/translations/zh/products/cli-api-reference/pages/commands.mdx index 1d2914ff8..18ba15f83 100644 --- a/fern/translations/zh/products/cli-api-reference/pages/commands.mdx +++ b/fern/translations/zh/products/cli-api-reference/pages/commands.mdx @@ -1,21 +1,20 @@ --- title: '命令' -description: 'Fern CLI 所有命令的完整参考，用于生成 SDK 和开发者文档。' +description: '生成 SDK 和开发者文档的所有 Fern CLI 命令的完整参考。' subtitle: '了解 Fern CLI 命令。' -sidebar-title: '命令' hideOnThisPage: true --- | 命令 | 描述 | |---------|-------------| -| [`fern init`](#fern-init) | 从 OpenAPI 规范或从头开始创建新的 Fern 项目 | +| [`fern init`](#fern-init) | 从 OpenAPI 规范或从头创建新的 Fern 项目 | | [`fern check`](#fern-check) | 验证 API 定义和配置 | | [`fern upgrade`](#fern-upgrade) | 将 Fern CLI 和生成器更新到最新版本 | | [`fern login`](#fern-login) | 通过 GitHub、Google、Postman 或企业 SSO 登录 Fern CLI | -| [`fern logout`](#fern-logout) | 从 Fern CLI 注销 | -| [`fern export`](#fern-export) | 导出 API 的 OpenAPI 规范 | -| [`fern api update`](#fern-api-update) | 手动更新 OpenAPI 规范 | +| [`fern logout`](#fern-logout) | 退出登录 Fern CLI | +| [`fern export`](#fern-export) | 为你的 API 导出 OpenAPI 规范 | +| [`fern api update`](#fern-api-update) | 手动更新你的 OpenAPI 规范 | | [`fern api enrich`](#fern-api-enrich) | 将覆盖文件中的 `x-fern-examples` 合并到原生 OpenAPI 示例中 | ## 文档命令 @@ -23,22 +22,22 @@ hideOnThisPage: true | 命令 | 描述 | |---------|-------------| | [`fern docs dev`](#fern-docs-dev) | 运行本地文档预览服务器 | -| [`fern docs diff`](#fern-docs-diff) Beta | 生成预览和生产文档之间的视觉差异 | -| [`fern generate --docs`](#fern-generate---docs) | 构建并发布文档更新 | +| [`fern docs diff`](#fern-docs-diff) Beta | 生成预览版和生产版文档之间的可视化差异 | +| [`fern generate --docs`](#fern-generate---docs) | 构建和发布文档更新 | | [`fern docs preview list`](#fern-docs-preview-list) | 列出所有预览部署 | | [`fern docs preview delete`](#fern-docs-preview-delete) | 删除预览部署 | | [`fern docs md check`](#fern-docs-md-check) | 验证文档文件中的 MDX 语法 | -| [`fern docs theme export`](#fern-docs-theme-export) | 从 `docs.yml` 导出主题兼容字段到独立目录 | -| [`fern docs theme upload`](#fern-docs-theme-upload) | 上传主题到 Fern 注册表 | -| [`fern docs theme list`](#fern-docs-theme-list) | 列出组织的所有主题 | +| [`fern docs theme export`](#fern-docs-theme-export) | 将 `docs.yml` 中符合主题条件的字段导出到独立目录 | +| [`fern docs theme upload`](#fern-docs-theme-upload) | 将主题上传到 Fern 的注册表 | +| [`fern docs link check`](#fern-docs-link-check) | 检查实时文档站点中的失效链接 | +| [`fern docs theme list`](#fern-docs-theme-list) | 列出你组织的所有主题 | ## SDK 生成命令 | 命令 | 描述 | |---------|-------------| -| [`fern generate`](#fern-generate) | 构建并发布 SDK 更新 | -| [`fern write-definition`](#fern-write-definition) | 将 OpenAPI 规范转换为 [Fern Definition](/learn/api-definitions/ferndef/overview) | -| [`fern write-overrides`](#fern-write-overrides) | 创建 OpenAPI 自定义 | +| [`fern generate`](#fern-generate) | 构建和发布 SDK 更新 | +| [`fern write-overrides`](#fern-write-overrides) | 创建 OpenAPI 自定义配置 | | [`fern generator upgrade`](#fern-generator-upgrade) | 将 SDK 生成器更新到最新版本 | ## 详细命令文档 @@ -46,7 +45,7 @@ hideOnThisPage: true - 使用 `fern init` 在当前文件夹中初始化新的 Fern 工作空间。默认情况下，您将看到 IMDb API 示例。 + 使用 `fern init` 在当前文件夹中初始化新的 Fern 工作区。默认情况下，你会看到 IMDb API 示例。 ```bash @@ -54,27 +53,14 @@ hideOnThisPage: true ``` - 使用 OpenAPI 初始化时，您的项目结构将如下所示： + 使用 OpenAPI 初始化时，你的项目结构如下所示： - + - - - - - - 对于 Fern Definition 初始化（不使用 OpenAPI），您将看到以下结构： - - - - - - - - + @@ -93,7 +79,7 @@ hideOnThisPage: true ### docs - 通过添加 `--docs`，您还将获得一个包含 API Reference 部分的示例文档网站。 + 通过添加 `--docs`，你还会得到一个 API 示例文档网站，包含 API 参考部分。 ```bash fern init --docs @@ -112,21 +98,21 @@ hideOnThisPage: true background: '#000000' ``` - 要发布 API 文档，请运行 [`fern generate --docs`](/learn/cli-api/cli-reference/commands#fern-generate---docs)。 + 要发布 API 文档，运行 [`fern generate --docs`](/learn/cli-api/cli-reference/commands#fern-generate---docs)。 ### mintlify - 通过添加 `--mintlify PATH_TO_MINT_CONFIG`，CLI 将根据 `mint.json` 文件自动将您的 Mintlify 文档文件夹转换为 Fern 文档网站。 + 通过添加 `--mintlify PATH_TO_MINT_CONFIG`，CLI 会自动根据 `mint.json` 文件将你的 Mintlify 文档文件夹转换为 Fern 文档站点。 ```bash fern init --mintlify PATH_TO_MINT_CONFIG ``` - CLI 将创建一个具有以下结构的 `fern/` 文件夹： + CLI 将创建一个 `fern/` 文件夹，结构如下： - + @@ -134,35 +120,33 @@ hideOnThisPage: true ### readme - `fern init` 命令支持导入 Readme 生成的文档网站。这需要安装本地 chromium 浏览器实例。 - 您可以通过从源代码安装 `fern` cli 来确保已安装，请按照[这里](https://github.com/fern-api/fern/blob/main/CONTRIBUTING.md)的说明进行操作。 + `fern init` 命令支持导入 Readme 生成的文档站点。这需要本地安装 chromium 浏览器实例。 + 你可以按照[这里](https://github.com/fern-api/fern/blob/main/CONTRIBUTING.md)的说明从源码安装 `fern` cli 来确保安装了这个依赖。 - 通过添加 `--readme URL_TO_README_DOCS_SITE`，CLI 将自动将 Readme 生成的文档网站转换为 Fern 文档网站。 + 通过添加 `--readme URL_TO_README_DOCS_SITE`，CLI 会自动将 Readme 生成的文档站点转换为 Fern 文档站点。 ```bash fern init --readme URL_TO_README_DOCS_SITE ``` - CLI 将创建一个具有以下结构的 `fern/` 文件夹： + CLI 将创建一个 `fern/` 文件夹，结构如下： - + - 有关入门的更多信息，请查看我们的[快速入门指南](/learn/docs/getting-started/quickstart) + 更多关于入门的信息，请查看我们的[快速入门指南](/learn/docs/getting-started/quickstart) - 使用 `fern export` 为您的 API 生成 OpenAPI 规范。 - - 当您以 OpenAPI 以外的格式（例如 [Fern Definition](/api-definitions/ferndef/overview)）定义了 API 并需要将其导出为 OpenAPI 规范以与其他工具或服务集成时，此命令非常有用。 + 使用 `fern export` 为你的 API 生成 OpenAPI 规范。当你用 OpenAPI 以外的格式（如 [Fern Definition](/learn/api-definitions/ferndef/overview)）定义 API 并需要将其导出以集成其他工具或服务时，这很有用。 @@ -174,7 +158,7 @@ hideOnThisPage: true ### api - 当您在 `fern/apis/` 文件夹中定义了多个 API 时，使用 `--api` 指定要导出的 API。 + 当你在 `fern/apis/` 文件夹中定义了多个 API 时，使用 `--api` 指定要导出哪个 API。 ```bash @@ -186,7 +170,7 @@ hideOnThisPage: true - 使用 `fern generate` 运行 Fern 编译器并为您的 API 创建 SDK。 + 使用 `fern generate` 运行 Fern 编译器并为你的 API 创建 SDK。 ```bash @@ -196,23 +180,23 @@ hideOnThisPage: true ### group - 使用 `--group ` 指定要运行的生成器组。您可以使用组名或别名。别名在您的 [`generators.yml`](/learn/sdks/reference/generators-yml#aliases) 中定义并映射到多个组，允许您通过单个命令并行运行多个组。 + 使用 `--group ` 指定要运行哪个生成器组。你可以使用组名或别名。别名[在你的 `generators.yml` 中定义](/learn/sdks/reference/generators-yml#aliases)，映射到多个组，允许你通过单个命令并行运行多个组。 ```bash # 运行特定组 fern generate --group python-sdk - # 运行在"all"别名中定义的所有组 + # 运行"all"别名中定义的所有组 fern generate --group all - # 运行在"frontend"别名中定义的所有组 + # 运行"frontend"别名中定义的所有组 fern generate --group frontend # 本地运行特定组（自托管） fern generate --group python-sdk --local ``` - 您还可以在 `generators.yml` 中将别名设置为 `default-group`，这样运行不带任何参数的 `fern generate` 将运行该别名中的所有组。 + 你也可以在 `generators.yml` 中设置别名作为 `default-group`，这样不带任何参数运行 `fern generate` 会运行该别名中的所有组。 `--group` 标志可以与其他标志组合使用，如用于[自托管 SDK 生成](/learn/sdks/deep-dives/self-hosted)的 `--local`、用于本地测试的 `--preview` 或用于指定 SDK 版本的 `--version`。 @@ -220,7 +204,6 @@ hideOnThisPage: true 使用 `--preview` 在发布前本地测试 SDK 更改。这在开发期间特别有用： - 将 SDK 生成到本地 `.preview/` 文件夹 - - 允许在 Fern 定义上快速迭代 - 不会将更改发布到包管理器或 GitHub ```bash @@ -233,7 +216,7 @@ hideOnThisPage: true ### api - 使用 `--api ` 为 SDK 生成指定 API。当项目包含多个 API 定义时这很有用。API 名称应与 `fern/apis/` 文件夹中的目录名称匹配。 + 使用 `--api ` 指定用于 SDK 生成的 API。当项目包含多个 API 定义时很有用。API 名称应匹配 `fern/apis/` 文件夹中的目录名。 ```bash fern generate --api public-api @@ -241,21 +224,21 @@ hideOnThisPage: true ### version - 使用 `--version` 指定 SDK 版本号，通常遵循语义版本控制（semver）格式（`MAJOR.MINOR.PATCH`）。这在发布 SDK 版本的 CI/CD 流水线中特别有用。 + 使用 `--version` 指定 SDK 版本号，通常遵循语义版本控制（semver）格式（`MAJOR.MINOR.PATCH`）。这在 CI/CD 流水线中发布 SDK 版本时特别有用。 ```bash - # 使用版本 2.11.0 生成所有 SDK + # 生成版本为 2.11.0 的所有 SDK fern generate --version 2.11.0 - # 为支付 API 的 Python SDK 生成版本 1.2.3 + # 为 payments API 生成版本为 1.2.3 的 Python SDK fern generate --api payments-api --group python-sdk --version 1.2.3 ``` ### fernignore - 使用 `--fernignore` 为 SDK 生成指定自定义 `.fernignore` 文件路径。这允许您临时测试不同的忽略配置，而无需修改存储库中已提交的 `.fernignore`。 + 使用 `--fernignore` 为 SDK 生成指定自定义 `.fernignore` 文件路径。这允许你临时测试不同的忽略配置，而不修改仓库中提交的 `.fernignore`。 - Fern 将使用指定的文件而不是主分支上的文件，并将新的 `.fernignore` 作为生成过程的一部分提交到您的存储库。 + Fern 将使用指定的文件而不是主分支上的文件，并将新的 `.fernignore` 作为生成过程的一部分提交到你的仓库。 ```bash fern generate --fernignore ./custom-fernignore @@ -263,7 +246,7 @@ hideOnThisPage: true ### local - 使用 `--local` 在您自己的机器上运行 SDK 生成，而不是使用 Fern 的云基础设施。这对于有严格安全或合规要求的组织很有用。请参阅[自托管 SDK](/learn/sdks/deep-dives/self-hosted) 获取设置说明。 + 使用 `--local` 在你自己的机器上运行 SDK 生成，而不是使用 Fern 的云基础设施。这对于有严格安全或合规要求的组织很有用。设置说明请参阅[自托管 SDK](/learn/sdks/deep-dives/self-hosted)。 ```bash # 本地生成所有 SDK @@ -274,17 +257,17 @@ hideOnThisPage: true ``` - 您的机器上必须运行 Docker 守护进程，因为 SDK 生成在 Docker 容器内运行。 + 你的机器上必须运行 Docker 守护进程，因为 SDK 生成在 Docker 容器内运行。 - 默认情况下，CLI 从 Docker Hub 拉取生成器镜像。要从自定义容器注册表拉取，请在您的 `generators.yml` 中使用 [`image` 字段](/learn/sdks/reference/generators-yml#image) 而不是 `name`。请参阅[自定义容器注册表](/learn/sdks/deep-dives/self-hosted#optional-configure-a-custom-container-registry)了解详细信息。 + 默认情况下，CLI 从 Docker Hub 拉取生成器镜像。要从自定义容器注册表拉取，在 `generators.yml` 中使用 [`image` 字段](/learn/sdks/reference/generators-yml#image)而不是 `name`。详见[自定义容器注册表](/learn/sdks/deep-dives/self-hosted#optional-configure-a-custom-container-registry)。 ### force - 使用 `--force` 跳过生成过程中的确认提示。这在会阻塞流水线的交互式提示的 CI/CD 环境中很有用。 + 使用 `--force` 在生成期间跳过确认提示。这在 CI/CD 环境中很有用，因为交互式提示会阻塞流水线。 ```bash - # 不带确认提示生成 + # 无确认提示生成 fern generate --group python-sdk --force ``` @@ -293,12 +276,12 @@ hideOnThisPage: true - `--broken-links` 和 `--strict-broken-links` 标志已弃用。请在 `docs.yml` 中使用 [`broken-links` 验证规则](/learn/docs/configuration/site-level-settings#check-configuration)。 - - 您还可以使用 [Fern Dashboard](https://dashboard.buildwithfern.com/) 验证实时发布网站上的内部和外部链接。 + `--broken-links` 和 `--strict-broken-links` 标志已弃用。请改用 `docs.yml` 中的 [`broken-links` 验证规则](/learn/docs/configuration/site-level-settings#check-configuration)。 - 使用 `fern check` 验证您的 API 定义和 Fern 配置，包括 [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson)、`generators.yml` 和 `docs.yml`。它检查损坏的链接、无效的 API 示例、配置错误等。当所有检查通过时，该命令不产生输出。 + 使用 `fern check` 验证你的 API 定义和 Fern 配置，包括 [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson)、`generators.yml` 和 `docs.yml`。它检查失效链接、无效的 API 示例、配置错误等。当所有检查通过时，命令不产生输出。 + + 大多数 `fern check` 规则——包括 [`broken-links`](/learn/docs/configuration/site-level-settings#check-configuration)——根据从**本地**配置构建的导航树进行验证，不会爬取你的实时部署站点或跟踪外部 URL。例外是 [`missing-redirects` 规则](/learn/docs/seo/redirects#catching-missing-redirects)，它将本地导航与先前发布的状态进行比较，因此需要 `fern login` 或 `FERN_TOKEN`。 ```bash @@ -306,7 +289,7 @@ hideOnThisPage: true ``` - 您可以在 `docs.yml` 文件中[使用 `check.rules` 属性](/learn/docs/configuration/site-level-settings#check-configuration)配置 `fern check` 运行的验证规则的严重性。 + 你可以[使用 `check.rules` 属性](/learn/docs/configuration/site-level-settings#check-configuration)在 `docs.yml` 文件中配置 `fern check` 运行的验证规则的严重性。 ```yaml docs.yml check: @@ -316,6 +299,10 @@ hideOnThisPage: true missing-redirects: error ``` + + 要检查已发布站点上的链接，请改用 [`fern docs link check`](#fern-docs-link-check) 或 [Fern Dashboard](https://dashboard.buildwithfern.com/) 中的链接检查器。 + + ### api 使用 `--api ` 指定要检查的 API。 @@ -326,7 +313,7 @@ hideOnThisPage: true ### warnings - 使用 `--warnings` 除了记录错误外还记录警告。 + 使用 `--warnings` 除了错误外还记录警告。 ```bash fern check --warnings @@ -365,7 +352,7 @@ hideOnThisPage: true - 使用 `fern generate --docs` 为您的 API 创建文档网站。 + 使用 `fern generate --docs` 为你的 API 创建文档站点。 ```bash @@ -375,7 +362,7 @@ hideOnThisPage: true ### instance - 使用 `--instance` 指定要为 `docs.yml` 中的哪个实例 URL 生成文档。 + 使用 `--instance` 指定 `docs.yml` 中的哪个实例 URL 用于生成文档。 ```bash fern generate --docs --instance your-organization.docs.buildwithfern.com @@ -383,7 +370,7 @@ hideOnThisPage: true ### preview - 使用 `--preview` 在将更改发布到生产网站之前预览文档更新。 + 使用 `--preview` 在发布更改到生产站点之前预览文档更新。 ```bash fern generate --docs --preview @@ -391,18 +378,18 @@ hideOnThisPage: true ### id - 使用 `--id` 与 `--preview` 一起创建稳定的命名预览链接。预览 URL 遵循格式 `{org}-preview-{id}.docs.buildwithfern.com`，因此使用相同的 `--id` 重新运行会就地更新现有预览，而不是创建新预览。 + 与 `--preview` 一起使用 `--id` 创建稳定的命名预览链接。预览 URL 遵循格式 `{org}-preview-{id}.docs.buildwithfern.com`，因此用相同的 `--id` 重新运行会就地更新现有预览，而不是创建新的。 ```bash fern generate --docs --preview --id my-feature # -> https://your-org-preview-my-feature.docs.buildwithfern.com ``` - 这在您希望每个拉取请求有一个预览 URL 的 CI 工作流程中很有用。请参阅[预览更改](/learn/docs/preview-publish/preview-changes#preview-links)了解详细信息。 + 这在 CI 工作流中很有用，你希望每个拉取请求有一个预览 URL。详见[预览更改](/learn/docs/preview-publish/preview-changes#preview-links)。 ### force - 当重用已存在的 `--id` 时，Fern 会提示您确认覆盖。使用 `--force` 跳过确认。这在 GitHub Actions 中会自动检测到，但在其他 CI 环境（如 Azure Pipelines）中需要。 + 当重用已存在的 `--id` 时，Fern 会提示你确认覆盖。使用 `--force` 跳过确认。这在 GitHub Actions 中会自动检测，但在其他 CI 环境（如 Azure Pipelines）中需要。 ```bash fern generate --docs --preview --id my-feature --force @@ -412,7 +399,7 @@ hideOnThisPage: true - 使用 `fern docs preview list` 列出您组织的所有预览部署。 + 使用 `fern docs preview list` 列出你组织的所有预览部署。 ```bash @@ -430,7 +417,7 @@ hideOnThisPage: true ### page - 使用 `--page` 指定要显示结果的页面。 + 使用 `--page` 指定显示哪一页结果。 ```bash fern docs preview list --page 2 @@ -440,7 +427,7 @@ hideOnThisPage: true - 使用 `fern docs preview delete` 删除使用 `fern generate --docs --preview` 生成的预览部署。`` 参数是要删除的完整预览 URL。 + 使用 `fern docs preview delete` 删除用 `fern generate --docs --preview` 生成的预览部署。`` 参数是要删除的完整预览 URL。 ```bash @@ -452,7 +439,7 @@ hideOnThisPage: true - 使用 `fern docs dev` 运行本地开发服务器来预览您的文档。 + 使用 `fern docs dev` 运行本地开发服务器来预览你的文档。 ```bash @@ -460,16 +447,16 @@ hideOnThisPage: true ``` - + 在 Windows 上，`fern docs dev` 需要启用[长路径支持](https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation#enable-long-paths-in-windows-10-version-1607-and-later)。 - 要启用长路径支持，请在提升的 PowerShell 提示符中运行以下命令，然后重启您的终端： + 要启用长路径支持，在提升的 PowerShell 提示符中运行以下命令，然后重启终端： ```powershell New-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1 -PropertyType DWORD -Force ``` - 如果您无法启用长路径支持，请使用 [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install) 在 Linux 环境中运行 `fern docs dev`。 + 如果无法启用长路径支持，请使用 [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install) 在 Linux 环境中运行 `fern docs dev`。 ### port @@ -482,9 +469,76 @@ hideOnThisPage: true + + + 使用 `fern docs link check` 扫描实时文档站点以查找失效链接。该命令爬取已发布的站点，检查每个链接，并报告失效（404）和被阻止（403）的 URL 及其来源页面。 + + + ```bash + fern docs link check [--url ] [--output ] + ``` + + + + 与 [`fern check`](#fern-check) 中只验证本地 YAML 导航树中内部链接的 [`broken-links` 规则](#fern-check)不同，`fern docs link check` 检查实时部署站点上的所有链接——内部和外部。 + + + 默认情况下，命令从 `docs.yml` 中的 `instances` 自动检测你的文档 URL。当所有链接有效时，命令以成功消息退出。 + + 命令首先抓取站点上的每个页面，然后检查找到的每个链接。当发现失效链接时，输出包括摘要和按状态码和源文件路径分组的失效 URL 列表。 + + ```plaintext + ◆ Checking links on your-org.docs.buildwithfern.com... + + Scraping pages [████████████████████] 100% | 42/42 + Checking links [████████████████████] 100% | 240/240 + + Finished in 2 minutes, 23 seconds + + Summary + Pages scanned 42 + Links checked 240 + ✓ Working 228 + ✗ Broken 8 (external) + ⚠ Blocked 4 + + ───────────────────────────────────── + + External Broken Links (8) + + ✗ https://example.com/removed-page → 404 + fern/pages/quickstart.mdx + fern/pages/overview.mdx + + ✗ https://example.com/old-endpoint → 404 + fern/pages/integrations.mdx + ``` + + ### url + + 使用 `--url` 指定要检查的文档站点。当你有多个实例或想检查预览部署时很有用。 + + ```bash + fern docs link check --url https://your-org.docs.buildwithfern.com + ``` + + ### output + + 使用 `--output` 控制输出格式。支持的值有 `text`（默认）、`json` 和 `csv`。 + + ```bash + # JSON 输出用于编程使用 + fern docs link check --output json + + # CSV 输出用于电子表格或报告 + fern docs link check --output csv + ``` + + + - 使用 `fern docs md check` 验证导航配置中引用的所有文档页面的 MDX 语法，包括 `docs.yml`、版本配置文件和产品特定的 YAML 文件。 + 使用 `fern docs md check` 验证导航配置中引用的所有文档页面的 MDX 语法，包括 `docs.yml`、版本化配置文件和产品特定的 YAML 文件。 ```bash @@ -492,7 +546,7 @@ hideOnThisPage: true ``` - 该命令解析每个 MDX 文件并报告语法错误，包含文件路径和行:列号。该命令考虑 frontmatter 偏移量，因此报告的行号与文件中的实际行对应。 + 该命令解析每个 MDX 文件并报告语法错误，包含文件路径和行:列号。命令考虑前言偏移，因此报告的行号对应文件中的实际行。 ```plaintext fern/pages/quickstart.mdx:12:5 @@ -502,7 +556,7 @@ hideOnThisPage: true Expected a closing tag for `` before the end of `paragraph` ``` - 当所有文件都有效时，您将看到成功消息： + 当所有文件有效时，你会看到成功消息： ```plaintext ✓ All 42 MDX files are valid @@ -513,7 +567,7 @@ hideOnThisPage: true Beta - 使用 `fern docs diff` 在预览部署和生产文档之间生成视觉差异。此命令旨在用于 [GitHub Actions](https://github.com/fern-api/docs/blob/main/.github/workflows/preview-docs.yml)。它捕获两个版本的截图并创建并排比较图像。 + 使用 `fern docs diff` 在预览部署和生产文档之间生成可视化差异。此命令旨在用于 [GitHub Actions](https://github.com/fern-api/docs/blob/main/.github/workflows/preview-docs.yml)。它捕获两个版本的截图并创建并排比较图像。 ```bash @@ -521,7 +575,7 @@ hideOnThisPage: true ``` - 传递来自 `fern generate --docs --preview` 的预览 URL 和一个或多个 MDX 文件路径。差异图像默认保存到 `.fern/diff`。 + 传入来自 `fern generate --docs --preview` 的预览 URL 和一个或多个 MDX 文件路径。差异图像默认保存到 `.fern/diff`。 ```bash fern docs diff acme-preview-abc123.docs.buildwithfern.com fern/pages/intro.mdx fern/pages/quickstart.mdx @@ -539,7 +593,7 @@ hideOnThisPage: true - 使用 `fern upgrade` 将 [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson) 中的编译器版本升级到最新版本。它还将 `generators.yml` 中的生成器升级到其最低兼容版本。 + 使用 `fern upgrade` 将 [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson) 中的编译器版本升级到最新版本。它还会将 `generators.yml` 中的生成器升级到其最低兼容版本。 ```bash @@ -551,7 +605,7 @@ hideOnThisPage: true - 使用 `fern login` 通过 GitHub 或 Google 登录 Fern CLI。登录允许您加入 GitHub 组织、获得权限并为项目做出贡献。 + 使用 `fern login` 通过 GitHub 或 Google 登录 Fern CLI。登录后，你可以加入 GitHub 组织、获得权限并贡献项目。 ```bash @@ -561,11 +615,11 @@ hideOnThisPage: true ``` - 默认情况下，`fern login` 打开浏览器进行 GitHub、Google 或 Postman 身份验证。有两种替代流程可用： + 默认情况下，`fern login` 打开浏览器进行 GitHub、Google 或 Postman 认证。有两种替代流程可用： ### device-code - 在无法自动打开浏览器的环境中（例如 SSH 会话或容器），使用 `--device-code` 通过设备代码授权登录。 + 在浏览器无法自动打开的环境中（如 SSH 会话或容器），使用 `--device-code` 通过设备代码授权登录。 ```bash fern login --device-code @@ -573,21 +627,21 @@ hideOnThisPage: true ### email - 使用 `--email` 通过企业 SSO 登录。传递与您组织的 SSO 提供商关联的电子邮件地址。 + 使用 `--email` 通过企业 SSO 登录。传入与组织 SSO 提供商关联的邮箱地址。 ```bash fern login --email user@example.com ``` - 要启用 CI/CD，请使用 [`fern token`](/learn/cli-api/cli-reference/commands#fern-token)。 + 要启用 CI/CD，使用 [`fern token`](/learn/cli-api/cli-reference/commands#fern-token)。 - 使用 `fern logout` 从 Fern CLI 注销。这将清除您的身份验证凭据并撤销对您的 GitHub 组织和权限的访问。 + 使用 `fern logout` 退出登录 Fern CLI。这将清除你的认证凭据并撤销对 GitHub 组织和权限的访问。 ```bash @@ -595,7 +649,7 @@ hideOnThisPage: true ``` - 注销后，您需要再次运行 [`fern login`](#fern-login) 来访问受保护的功能。 + 退出登录后，你需要再次运行 [`fern login`](#fern-login) 来访问受保护的功能。 @@ -603,56 +657,13 @@ hideOnThisPage: true - 请参阅[发布您的文档](/learn/docs/preview-publish/publishing-your-docs#usage-in-github-actions)，了解在自动化发布工作流程中使用此令牌的说明。 - - + 请参阅[发布你的文档](/learn/docs/preview-publish/publishing-your-docs#usage-in-github-actions)了解在自动化发布工作流中使用此令牌的说明。 - - - 使用 `fern write-definition` 将您的 OpenAPI 规范转换为 Fern Definition。您必须有一个包含 `.json` 或 `.yaml` 格式的 OpenAPI 规范文件的 `fern/openapi/` 文件夹。 - - - ```bash - fern write-definition [--api ] - ``` - - - 运行此命令时，会在 `fern/` 内创建一个名为 `.definition/` 的新文件夹。 - - - - - - - - - - - - - - - - - 如果您没有看到 `.definition/` 文件夹，请使用适当的命令或配置来查看隐藏文件夹（在 `bash` 和 `zsh` 中使用 `ls -a`）。 - - - 如果您的 `fern/` 文件夹同时包含 `openapi/` 和 `definition/` 文件夹，Fern 默认读取您的 OpenAPI 规范。要使用您的 Fern Definition 作为输入，您必须： - - 将 `.definition/` 文件夹重命名为 `definition/`。 - - 删除或重命名 `openapi/` 文件夹。例如，您可以将其重命名为 `.openapi/`。 - - ### api - - 如果您在 `fern/apis/` 文件夹中定义了多个 API，请使用 `--api` 指定要为其编写定义的 API。 - - ```bash - fern write-definition --api public-api - ``` - 使用 `fern write-overrides` 生成基本的 OpenAPI 覆盖文件。覆盖文件允许对 API 规范进行可逆修改，包括为 Fern Docs 中的代码片段添加请求和响应示例。 + 使用 `fern write-overrides` 生成基本的 OpenAPI 覆盖文件。覆盖文件允许对 API 规范进行可逆修订，包括为 Fern Docs 中的代码片段添加请求和响应示例。 ```bash @@ -660,14 +671,14 @@ hideOnThisPage: true ``` - 运行此命令时，会在 `fern/openapi/` 内创建一个名为 `openapi-overrides.yml` 的新文件。 + 运行时，此命令在 `fern/openapi/` 中创建一个名为 `openapi-overrides.yml` 的新文件。 - + @@ -675,7 +686,7 @@ hideOnThisPage: true ### api - 如果定义了多个 API，请使用 `--api` 指定要对其运行命令的 API。 + 如果定义了多个 API，使用 `--api` 指定要运行命令的 API。 ```bash fern write-overrides --api public-api @@ -683,7 +694,7 @@ hideOnThisPage: true ### exclude-models - 使用 `--exclude-models` 在生成初始覆盖时存根模型（除了端点）。 + 使用 `--exclude-models` 在生成初始覆盖时排除模型（除了端点）。 ```bash fern write-overrides --exclude-models @@ -692,10 +703,10 @@ hideOnThisPage: true - 使用 `fern generator upgrade` 将 `generators.yml` 中的所有生成器更新到其最新版本。 + 使用 `fern generator upgrade` 将 `generators.yml` 中的所有生成器更新到最新版本。 - 这与更新 Fern CLI 版本的 `fern upgrade` 不同。使用这两个命令来保持整个 Fern 工具链的最新状态。 + 这与更新 Fern CLI 版本的 `fern upgrade` 不同。使用这两个命令来保持整个 Fern 工具链最新。 @@ -706,10 +717,10 @@ hideOnThisPage: true 此命令将： - 检查 `generators.yml` 中指定的所有生成器的更新 - - 将生成器版本更新到其最新兼容版本 + - 将生成器版本更新到最新兼容版本 - 保持与当前 Fern 编译器版本的兼容性 - 当有可用更新时，您可能会看到： + 当有可用更新时，你可能会看到： ```plaintext ┌───────────────────────────────────────────────────────────────────────────────────┐ @@ -747,7 +758,7 @@ hideOnThisPage: true ### group - 使用 `--group` 升级 `generators.yml` 中特定组内的生成器。如果未指定，将升级指定类型的所有生成器。 + 使用 `--group` 升级 `generators.yml` 中特定组内的生成器。如果未指定，指定类型的所有生成器都会被升级。 ```bash fern generator upgrade --group public @@ -759,11 +770,11 @@ hideOnThisPage: true fern generator upgrade --include-major ``` - 使用 `--include-major` 包括主要版本升级。默认跳过主要版本以防止破坏性更改。 + 使用 `--include-major` 包含主要版本升级。默认跳过主要版本以防止破坏性更改。 - 从 `generators.yml` 中指定的 `origin` 拉取最新的 OpenAPI 规范并更新本地规范。或者，您可以[通过设置 GitHub Action 来自动化此过程](/api-definitions/openapi/sync-your-open-api-specification)。 + 从 `generators.yml` 中指定的 `origin` 拉取最新的 OpenAPI 规范并更新本地规范。或者，你可以[通过设置 GitHub Action 来自动化此过程](/api-definitions/openapi/sync-your-open-api-specification)。 ```bash @@ -773,7 +784,7 @@ hideOnThisPage: true ### api - 如果 `generators.yml` 中有多个定义了 `origin` 的规范，请使用 `--api` 指定要更新的 API。如果您不指定 API，所有有 `origin` 的 OpenAPI 规范都将被更新。 + 如果 `generators.yml` 中有多个定义了 `origin` 的规范，使用 `--api` 指定要更新的 API。如果不指定 API，所有有 `origin` 的 OpenAPI 规范都会被更新。 ```bash @@ -784,7 +795,7 @@ hideOnThisPage: true - 使用 `fern api enrich` 将 [AI 生成的示例](/learn/docs/ai-features/ai-examples)或手动创作的 [`x-fern-examples`](/learn/api-definitions/openapi/extensions/request-response-examples) 转换为任何兼容 OpenAPI 的工具都可以使用的可移植 OpenAPI 示例。 + 使用 `fern api enrich` 将 [AI 生成的示例](/learn/docs/ai-features/ai-examples)或手动编写的 [`x-fern-examples`](/learn/api-definitions/openapi/extensions/request-response-examples) 转换为任何 OpenAPI 兼容工具都可以使用的可移植 OpenAPI 示例。 ```bash @@ -792,11 +803,11 @@ hideOnThisPage: true ``` - 该命令将覆盖文件中的示例合并到原生 OpenAPI `example` 字段中，并从输出中剥离 `x-fern-examples` 键。当端点有多个示例时，每个示例都作为命名条目存储在复数 `examples` 字段下。 + 该命令将覆盖文件中的示例合并到原生 OpenAPI `example` 字段中，并从输出中删除 `x-fern-examples` 键。当端点有多个示例时，每个示例都作为命名条目存储在复数 `examples` 字段下。 该命令需要两个标志： - - `-f`（或 `--file`）— 包含 `x-fern-examples` 的覆盖文件（例如，`ai_examples_override.yml`）。 + - `-f`（或 `--file`）— 包含 `x-fern-examples` 的覆盖文件（如 `ai_examples_override.yml`）。 - `-o`（或 `--output`）— 丰富输出文件的路径。支持 `.yml` 和 `.json` 扩展名。 ```bash @@ -819,7 +830,7 @@ hideOnThisPage: true - 使用 `fern docs theme export` 将 `docs.yml` 中的[主题兼容字段](/learn/docs/customization/global-themes)提取到独立目录中。导出的 `theme.yml` 及其资源然后可以通过 `fern docs theme upload` 上传。 + 使用 `fern docs theme export` 从你的 `docs.yml` 中提取[符合主题条件的字段](/learn/docs/customization/global-themes)到独立目录。导出的 `theme.yml` 及其资源然后可以用 `fern docs theme upload` 上传。 ```bash @@ -827,7 +838,7 @@ hideOnThisPage: true ``` - 默认情况下，文件写入 `./fern/theme/`。 + 默认情况下，文件被写入 `./fern/theme/`。 ### output @@ -841,7 +852,7 @@ hideOnThisPage: true - 使用 `fern docs theme upload` 将[主题](/learn/docs/customization/global-themes)上传到 Fern 的注册表。该命令从 `./fern/theme/` 读取 `theme.yml` 并连同任何引用的文件资源一起上传。 + 使用 `fern docs theme upload` 将[主题](/learn/docs/customization/global-themes)上传到 Fern 的注册表。该命令从 `./fern/theme/` 读取 `theme.yml` 并将其与任何引用的文件资源一起上传。 ```bash @@ -859,7 +870,7 @@ hideOnThisPage: true ### org - 使用 `--org` 覆盖来自 `fern.config.json` 的组织 ID。 + 使用 `--org` 覆盖 `fern.config.json` 中的组织 ID。 ```bash fern docs theme upload --org my-org @@ -869,7 +880,7 @@ hideOnThisPage: true - 使用 `fern docs theme list` 列出为您的组织上传的所有[主题](/learn/docs/customization/global-themes)。 + 使用 `fern docs theme list` 列出为你组织上传的所有[主题](/learn/docs/customization/global-themes)。 ```bash @@ -881,7 +892,7 @@ hideOnThisPage: true ### json - 使用 `--json` 将完整列表输出为 JSON 数组，包括 `updatedAt` 时间戳。 + 使用 `--json` 输出完整列表作为 JSON 数组，包括 `updatedAt` 时间戳。 ```bash fern docs theme list --json @@ -889,11 +900,11 @@ hideOnThisPage: true ### org - 使用 `--org` 覆盖来自 `fern.config.json` 的组织 ID。 + 使用 `--org` 覆盖 `fern.config.json` 中的组织 ID。 ```bash fern docs theme list --org my-org ``` - \ No newline at end of file + diff --git a/fern/translations/zh/products/cli-api-reference/pages/global-options.mdx b/fern/translations/zh/products/cli-api-reference/pages/global-options.mdx index c93f9be77..9b94b2599 100644 --- a/fern/translations/zh/products/cli-api-reference/pages/global-options.mdx +++ b/fern/translations/zh/products/cli-api-reference/pages/global-options.mdx @@ -1,12 +1,10 @@ --- title: '全局选项' description: 'Fern CLI 的全局选项' -subtitle: '了解 Fern CLI 全局选项。' -sidebar-title: '全局选项' +subtitle: '探索 Fern CLI 全局选项。' --- - -这些选项适用于任何 Fern CLI 命令，用于控制日志记录和获取帮助。 +这些选项可以与任何 Fern CLI 命令配合使用，用于控制日志记录和获取帮助。 | 选项 | 描述 | 示例 | |--------|-------------|---------| @@ -14,14 +12,13 @@ sidebar-title: '全局选项' | [`--log-level`](#log-level) | 设置日志详细程度 | `fern generate --log-level debug` | -使用 `--log-level debug` 在故障排除时查看详细输出。 +使用 `--log-level debug` 在排查问题时查看详细输出。 ## help -使用 `--help` 选项与任何 Fern CLI 命令一起查看说明和可用选项。 +在任何 Fern CLI 命令中使用 `--help` 选项来查看说明和可用选项。 - ```bash maxLines=10 title="fern add --help" fern add --help fern add @@ -38,29 +35,16 @@ Options: --group Add the generator to the specified group [string] ``` -```bash maxLines=10 title="fern write-definition --help" -fern write-definition --help -fern write-definition - -Write underlying Fern Definition for OpenAPI Specifications and API Dependencies. - -Options: - --help Show help [boolean] - --log-level [choices: "debug", "info", "warn", "error"] [default: "info"] - --api Only run the command on the provided API [string] -``` - - ## log-level -使用 `--log-level` 选项设置 Fern 日志输出的详细程度。默认级别为 `info`。 +使用 `--log-level` 选项来设置 Fern 日志输出的详细程度。默认级别是 `info`。 -可用级别（从详细到简略）： -- `debug`：调试消息、信息消息、警告和错误 -- `info`：信息消息、警告和错误 -- `warn`：仅警告和错误 -- `error`：仅错误消息 +可用级别（从最详细到最简略）： +- `debug`: 调试信息、提示信息、警告和错误 +- `info`: 提示信息、警告和错误 +- `warn`: 仅警告和错误 +- `error`: 仅错误信息 ```bash fern generate --log-level debug -``` \ No newline at end of file +``` diff --git a/fern/translations/zh/products/dashboard/pages/domains.mdx b/fern/translations/zh/products/dashboard/pages/domains.mdx index e85db8624..c3afd742f 100644 --- a/fern/translations/zh/products/dashboard/pages/domains.mdx +++ b/fern/translations/zh/products/dashboard/pages/domains.mdx @@ -1,18 +1,17 @@ --- title: 设置自定义域名 -description: 使用 Fern Dashboard 配置您的自定义域名，为子域名、子路径或根域名托管配置 DNS 记录。 -sidebar-title: 设置自定义域名 +description: 使用 Fern Dashboard 通过 DNS 记录为子域名、子路径或根域名托管配置您的自定义域名。 --- -[管理员](/learn/dashboard/configuration/permissions) 可以使用 [Fern Dashboard](https://dashboard.buildwithfern.com/) 配置以下任一自定义域名类型： -- **子域名**：`docs.mydomain.com` -- **子路径**：`mydomain.com/docs` -- **根域名**：`mydomain.com` +[管理员](/learn/dashboard/configuration/permissions)可以使用 [Fern Dashboard](https://dashboard.buildwithfern.com/) 来配置以下任何一种自定义域名类型： +- **子域名**: `docs.mydomain.com` +- **子路径**: `mydomain.com/docs` +- **根域名**: `mydomain.com` Dashboard 会根据您的域名类型自动提供正确的 DNS 记录。 - 或者，您可以[通过手动配置 DNS 记录来设置自定义域名](/learn/docs/preview-publish/setting-up-your-domain)。 + 或者，您也可以[通过手动配置 DNS 记录来设置自定义域名](/learn/docs/preview-publish/setting-up-your-domain)。 ## 设置 @@ -25,7 +24,7 @@ Dashboard 会根据您的域名类型自动提供正确的 DNS 记录。 -在**概述**选项卡的**域名**部分，选择**添加自定义域名**并输入您的域名。Dashboard 会显示您需要配置的 DNS 记录。 +在**概述**标签页的**域名**部分，选择**添加自定义域名**并输入您的域名。dashboard 会显示您需要配置的 DNS 记录。 @@ -43,13 +42,24 @@ instances: -登录到您的域名注册商并添加 Fern Dashboard 中显示的 DNS 记录。具体记录取决于您的域名类型（子域名、子路径或根域名）。 +登录到您的域名注册商，添加 Fern Dashboard 中显示的 DNS 记录。具体记录取决于您的域名类型（子域名、子路径或根域名）。 -添加 DNS 记录后，返回 Fern Dashboard 验证您的域名。SSL 会为您的域名自动配置，但可能需要几分钟才能在全球范围内传播。 +添加 DNS 记录后，返回到 Fern Dashboard 验证您的域名。SSL 会自动为您的域名配置，但可能需要几分钟才能在全球范围内传播。 -检查您是否可以从移动设备或无痕浏览器访问您的新文档站点。 +检查您是否可以从移动设备或隐身浏览器访问您的新文档站点。 - \ No newline at end of file + + +## 多源设置 + +对于[多源站点](/learn/docs/preview-publish/multi-source-docs) — 其中多个仓库发布到同一个自定义域名的不同子路径 — Dashboard 在域名的**设置**标签页上显示了**多仓库设置**卡片。这些设置适用于整个域名，而不是针对每个子路径。 + +该卡片配置： + +- **默认路径** — 设置用户在域名的根目录时跳转的位置。当 Fern 管理的页面作为根页面时很有用。 +- **搜索 / 询问 AI 范围** — 控制在一个子路径中的搜索是否返回所有子路径的结果（统一）还是保持在该子路径的范围内（分层）。 + +完整设置教程请参见[多源文档](/learn/docs/preview-publish/multi-source-docs)。 diff --git a/fern/translations/zh/products/dashboard/pages/overview.mdx b/fern/translations/zh/products/dashboard/pages/overview.mdx index 5e2e549a6..16d65fdf2 100644 --- a/fern/translations/zh/products/dashboard/pages/overview.mdx +++ b/fern/translations/zh/products/dashboard/pages/overview.mdx @@ -1,12 +1,11 @@ --- -title: 仪表板概述 +title: 仪表板概览 description: 从中央仪表板管理您的 Fern 项目、设置和团队。 -sidebar-title: 仪表板概述 --- -Fern 仪表板提供一个中心位置来管理您的项目、团队成员和设置。 +Fern 仪表板提供了一个管理您的项目、团队成员和设置的中心位置。 ## 设置 @@ -32,7 +31,7 @@ Fern 仪表板提供一个中心位置来管理您的项目、团队成员和设 icon="brands github" href="/learn/dashboard/configuration/github-repo" > - 将您的 GitHub 仓库连接到项目。 + 将您的 GitHub 仓库连接到您的项目。 为您的文档设置 AI 驱动的聊天功能。 + + 为跨多个仓库共享的域名配置默认路径和搜索范围。 + ## 指标 -监控和分析开发者如何与您的文档进行交互： +监控和分析开发者如何与您的文档互动： - 跟踪开发者和机器人如何与您的文档进行交互。 + 跟踪开发者和机器人如何与您的文档互动。 - 扫描您已发布的文档中的内部和外部损坏链接。 + 扫描您发布的文档中失效的内部和外部链接。 - 查看和响应页面反馈。 + 查看并回应页面上的反馈。

了解更多 @@ -86,7 +92,7 @@ Fern 仪表板提供一个中心位置来管理您的项目、团队成员和设 icon="regular messages" href="/learn/ask-fern/getting-started/what-is-ask-fern" > - 查看 AI 聊天对话历史。 + 查看 AI 聊天对话历史记录。

了解更多 @@ -107,14 +113,14 @@ Fern 仪表板提供一个中心位置来管理您的项目、团队成员和设 title="站点信息" icon="regular info-circle" > - 查看部署状态、域名、CLI 版本和 GitHub 仓库详细信息。 + 查看部署状态、域名、CLI 版本和 GitHub 仓库详情。 - 创建和管理 Fern Editor 会话。 + 创建和管理 Fern 编辑器会话。

了解更多 @@ -151,40 +157,41 @@ Fern 仪表板提供一个中心位置来管理您的项目、团队成员和设 icon="regular eye-slash" href="/learn/docs/preview-publish/publishing-your-docs#unpublishing-your-docs" > - 暂时让站点下线而不删除它。 + 临时下线站点而不删除它。 -Fern 仪表板提供一个中心位置来管理您的项目、团队成员和设置。 +The Fern Dashboard provides a central place to manage your projects, team members, and settings. -## 设置 +## Setup -访问您团队的[仪表板](https://dashboard.buildwithfern.com/)并完成初始设置步骤： +Visit your team's [Dashboard](https://dashboard.buildwithfern.com/) and complete initial setup steps: -- [设置自定义域名](/learn/dashboard/configuration/custom-domains)：配置您的自定义域名，自动配置 DNS 记录。 -- [成员权限](/learn/dashboard/configuration/permissions)：分配管理员、编辑者或查看者角色来管理仪表板和 CLI 访问权限。 -- [集成 GitHub](/learn/dashboard/configuration/github-repo)：将您的 GitHub 仓库连接到项目。 -- [启用 Ask Fern](/learn/docs/ai-features/ask-fern/overview)：为您的文档设置 AI 驱动的聊天功能。 +- [Set up custom domain](/learn/dashboard/configuration/custom-domains): Configure your custom domain with automatic DNS record provisioning. +- [Member permissions](/learn/dashboard/configuration/permissions): Assign Admin, Editor, or Viewer roles to manage Dashboard and CLI access. +- [Integrate GitHub](/learn/dashboard/configuration/github-repo): Connect your GitHub repository to your project. +- [Enable Ask Fern](/learn/docs/ai-features/ask-fern/overview): Set up AI-powered chat for your documentation. +- [Multi-source settings](/learn/dashboard/configuration/custom-domains#multi-source-settings): Configure default path and search scope for domains shared across multiple repositories. -## 指标 +## Metrics -监控和分析开发者如何与您的文档进行交互： +Monitor and analyze how developers interact with your documentation: -- **网站分析**：跟踪开发者和机器人如何与您的文档进行交互。 -- **搜索分析**：监控搜索查询，了解开发者在您的文档中寻找什么。 -- **损坏链接**：扫描您已发布的文档中的内部和外部损坏链接。 -- [反馈](/learn/docs/user-feedback)：查看和响应页面反馈。 -- [Ask Fern 对话](/learn/ask-fern/getting-started/what-is-ask-fern)：查看 AI 聊天对话历史。 +- **Web analytics**: Track how developers and bots interact with your documentation. +- **Search analytics**: Monitor search queries to understand what developers are looking for in your docs. +- **Broken links**: Scan your published docs for broken internal and external links. +- [Feedback](/learn/docs/user-feedback): View and respond to on-page feedback. +- [Ask Fern conversations](/learn/ask-fern/getting-started/what-is-ask-fern): Review AI chat conversation history. -## 站点管理 +## Site management -管理您的文档站点和团队协作： +Manage your documentation site and team collaboration: -- **站点信息**：查看部署状态、域名、CLI 版本和 GitHub 仓库详细信息。 -- [Fern Editor](/learn/docs/writing-content/fern-editor)：创建和管理 Fern Editor 会话。 -- [PDF 导出](/learn/dashboard/configuration/pdf-export)：将您的完整文档站点导出为 PDF。 -- [密码保护](/learn/dashboard/configuration/password-protection)：使用共享密码限制对您文档站点的访问。 -- [取消发布站点](/learn/docs/preview-publish/publishing-your-docs#unpublishing-your-docs)：暂时让站点下线而不删除它。 - \ No newline at end of file +- **Site information**: View deployment status, domains, CLI version, and GitHub repo details. +- [Fern Editor](/learn/docs/writing-content/fern-editor): Create and manage Fern Editor sessions. +- [PDF export](/learn/dashboard/configuration/pdf-export): Export your complete documentation site as a PDF. +- [Password protection](/learn/dashboard/configuration/password-protection): Restrict access to your docs site with a shared password. +- [Unpublish a site](/learn/docs/preview-publish/publishing-your-docs#unpublishing-your-docs): Temporarily take a site offline without deleting it. + diff --git a/fern/translations/zh/products/dashboard/pages/permissions.mdx b/fern/translations/zh/products/dashboard/pages/permissions.mdx index 8382be041..a2111f2c2 100644 --- a/fern/translations/zh/products/dashboard/pages/permissions.mdx +++ b/fern/translations/zh/products/dashboard/pages/permissions.mdx @@ -1,14 +1,13 @@ --- title: 成员权限 -description: 管理您组织的仪表板和 CLI 访问权限。 -sidebar-title: 成员权限 +description: 管理您组织的 Dashboard 和 CLI 访问权限。 --- -通过在 [Fern Dashboard](https://dashboard.buildwithfern.com/members) 中配置角色来控制每个团队成员在 Fern 中可以执行的操作。 +通过在 [Fern Dashboard](https://dashboard.buildwithfern.com/members) 中配置角色来控制每个团队成员在 Fern 中的操作权限。 ## 添加成员 -只有[管理员](#admin)可以添加成员。您的[计划](#team-members-by-plan)决定了可以添加的成员数量。 +只有[管理员](#admin)可以添加成员。您的[套餐](#team-members-by-plan)决定了可以添加多少成员。 @@ -20,15 +19,26 @@ sidebar-title: 成员权限 选择**添加成员**，然后选择以下方式之一邀请成员加入您的组织： -- **一次性链接**：分配一个[角色](#role-types)并为编辑者配置 [CLI 访问权限](#editor)。然后，选择**生成邀请链接**来创建一个可与任何人共享的一次性链接。 -- **电子邮件**：输入电子邮件地址，分配一个[角色](#role-types)，并为编辑者配置 [CLI 访问权限](#editor)。然后，选择**发送邀请**。 - -被邀请者将收到一封包含加入您在 Fern 中的组织链接的电子邮件。 +- **一次性链接**：分配[角色](#role-types)并为编辑者配置 [CLI 访问权限](#editor)。然后，选择**生成邀请链接**创建一个一次性使用的链接，您可以与任何人分享。 +- **邮箱**：输入邮箱地址，分配[角色](#role-types)，并为编辑者配置 [CLI 访问权限](#editor)。然后，选择**发送邀请**。 + +被邀请者会收到一封包含加入您在 Fern 中组织链接的邮件。 + + + + -要更改成员的角色或移除成员，请前往[成员](https://dashboard.buildwithfern.com/members)页面并选择成员姓名旁边的选项菜单。 +要更改成员角色或移除成员，请前往[成员](https://dashboard.buildwithfern.com/members)页面，选择成员姓名旁的选项菜单。 ## 角色类型 @@ -36,45 +46,45 @@ sidebar-title: 成员权限 角色控制两种类型的权限： -- **仪表板权限**：管理组织设置和成员、添加或更新自定义域名、查看分析数据以及使用 [Fern Editor](/learn/docs/writing-content/fern-editor)。 +- **Dashboard 权限**：管理组织设置和成员、添加或更新自定义域名、查看分析数据，以及使用 [Fern Editor](/learn/docs/writing-content/fern-editor)。 - **CLI 权限**：将 SDK 和文档发布到生产环境。本地开发和部署预览不需要 CLI 访问权限。 ### 管理员 -管理员对仪表板和 CLI 都有完全访问权限，包括编辑组织设置、管理成员、使用 Fern Editor 以及发布到生产环境。 +管理员对 Dashboard 和 CLI 都有完全访问权限，包括编辑组织设置、管理成员、使用 Fern Editor 以及发布到生产环境。 ### 编辑者 -编辑者可以查看分析数据和使用 Fern Editor。编辑者无法管理组织设置或成员。CLI 访问权限可为每个编辑者单独配置： +编辑者可以查看分析数据和使用 Fern Editor。编辑者不能管理组织设置或成员。每个编辑者的 CLI 访问权限可配置： - **有** CLI 访问权限的编辑者可以将 SDK 和文档站点发布到生产环境。 -- **无** CLI 访问权限的编辑者无法发布到生产环境。 +- **没有** CLI 访问权限的编辑者不能发布到生产环境。 - 所有编辑者都可以通过 CLI 部署预览。 ### 查看者 -查看者对仪表板（设置、分析数据）具有只读访问权限，并且可以通过 CLI 部署预览。查看者无法访问 Fern Editor。 +查看者对 Dashboard（设置、分析数据）拥有只读访问权限，可以通过 CLI 部署预览。查看者无法访问 Fern Editor。 -## 按角色划分的权限 +## 角色权限 -| 权限 | 管理员 | 编辑者 | 查看者 | -| -------------------- | ----- | --------------- | ----- | -| 管理组织设置 | 是 | 否 | 否 | -| 管理成员 | 是 | 否 | 否 | -| 添加或更新自定义域名 | 是 | 否 | 否 | -| 管理密码保护 | 是 | 否 | 否 | -| 查看仪表板和分析数据 | 是 | 是 | 是 | -| 发布到生产环境 | 是 | 按编辑者配置 | 否 | -| 部署预览 | 是 | 是 | 是 | -| 本地生成 | 是 | 是 | 是 | -| 使用 Fern Editor | 是 | 是 | 否 | +| 权限 | 管理员 | 编辑者 | 查看者 | +| ---------------------- | ----- | ------------------ | ------ | +| 管理组织设置 | 是 | 否 | 否 | +| 管理成员 | 是 | 否 | 否 | +| 添加或更新自定义域名 | 是 | 否 | 否 | +| 管理密码保护 | 是 | 否 | 否 | +| 查看 dashboard 和分析 | 是 | 是 | 是 | +| 发布到生产环境 | 是 | 按编辑者配置 | 否 | +| 部署预览 | 是 | 是 | 是 | +| 本地生成 | 是 | 是 | 是 | +| 使用 Fern Editor | 是 | 是 | 否 | -## 按计划划分的团队成员 +## 按套餐分配的团队成员 -您的[计划](https://buildwithfern.com/pricing)决定了可以添加到组织的成员数量： +您的[套餐](https://buildwithfern.com/pricing)决定了可以添加到组织的成员数量： -| 计划 | 团队成员 | -| --------- | ------- | -| Hobby | 2 | -| Pro | 5 | -| Enterprise| 自定义 | \ No newline at end of file +| 套餐 | 团队成员 | +| -------- | ------- | +| Hobby | 2 | +| Pro | 5 | +| Enterprise | 自定义 | diff --git a/fern/translations/zh/products/docs/pages/ai/llms-txt/customize-llms-txt.mdx b/fern/translations/zh/products/docs/pages/ai/llms-txt/customize-llms-txt.mdx index 123253993..7ecac05f3 100644 --- a/fern/translations/zh/products/docs/pages/ai/llms-txt/customize-llms-txt.mdx +++ b/fern/translations/zh/products/docs/pages/ai/llms-txt/customize-llms-txt.mdx @@ -1,36 +1,35 @@ --- title: 自定义 LLM 输出 -description: 使用 noindex 排除页面，使用 llms-only 和 llms-ignore 标签过滤内容，使用查询参数过滤端点输出，或提供您自己的自定义文件。 -sidebar-title: 自定义 LLM 输出 +description: 使用 noindex 排除页面、使用 llms-only 和 llms-ignore 标签过滤内容、使用查询参数过滤端点输出，或提供您自己的自定义文件。 --- -通过使用 `` 和 `` 标签在页面内过滤内容、使用查询参数过滤端点输出、使用 `noindex` 排除页面或提供您自己的自定义文件来自定义 LLM 从您的站点接收的内容。 +通过使用 `` 和 `` 标签在页面内过滤内容、使用查询参数过滤端点输出、使用 `noindex` 排除页面，或提供您自己的自定义文件来自定义 LLM 从您的站点接收的内容。 ## 页面内过滤 -在页面内，使用 `` 和 `` 标签来控制哪些内容暴露给 AI，哪些内容显示给文档站点上的人类读者。 +在页面内，使用 `` 和 `` 标签来控制在您的文档站点上哪些内容暴露给 AI 而非人类读者。 ### 仅供 AI 使用的内容 -`` 内容仅出现在外部代理（如 Claude、ChatGPT 或 Cursor）直接获取的 LLM 服务端点上：`/llms.txt`、`/llms-full.txt` 和每个页面的 [`.md`/`.mdx` 源文件](/learn/docs/developer-tools/view-markdown)。它在所有面向人类的界面中都被隐藏，包括渲染页面、[复制页面](/learn/docs/configuration/site-level-settings#page-actions-configuration)、搜索组件和 [Ask Fern](/learn/docs/ai-features/ask-fern/overview)。 +`` 内容仅出现在外部代理（如 Claude、ChatGPT 或 Cursor）直接获取的 LLM 服务端点上：`/llms.txt`、`/llms-full.txt`，以及每个页面的 [`.md`/`.mdx` 源文件](/learn/docs/ai-features/markdown)。它在所有面向人类的界面中都是隐藏的，包括渲染页面、[复制页面](/learn/docs/configuration/site-level-settings#page-actions-configuration)、搜索小部件和 [Ask Fern](/learn/docs/ai-features/ask-fern/overview)。 -使用 `` 用于： -- 对 AI 有帮助但过于冗长的技术上下文，如实现细节或架构说明 -- 会使人类 UI 混乱的代码相关元数据 +使用 `` 适用于： +- 对 AI 有用但冗长的技术上下文，如实现细节或架构说明 +- 会使人类 UI 变得混乱的代码相关元数据 - 帮助 AI 理解页面之间关系的交叉引用 ### 仅供人类使用的内容 -`` 内容出现在所有面向人类的界面上，包括渲染页面、[复制页面](/learn/docs/configuration/site-level-settings#page-actions-configuration)、搜索组件和 [Ask Fern](/learn/docs/ai-features/ask-fern/overview)（它会索引并像引用其他页面内容一样引用此内容）。它会从 LLM 服务端点（`/llms.txt`、`/llms-full.txt` 和每个页面的 `.md`/`.mdx` 源文件）中被移除。 +`` 内容出现在所有面向人类的界面上，包括渲染页面、[复制页面](/learn/docs/configuration/site-level-settings#page-actions-configuration)、搜索小部件和 [Ask Fern](/learn/docs/ai-features/ask-fern/overview)（它会索引并可以像任何其他页面内容一样引用它）。它会从 LLM 服务端点（`/llms.txt`、`/llms-full.txt` 和每个页面的 `.md`/`.mdx` 源文件）中被去除。 -使用 `` 用于： -- 营销 CTA 或推广内容 -- 仅供人类读者使用的导航提示 -- 应该仅保留在源文件中的内部注释 +使用 `` 适用于： +- 营销 CTA 或促销内容 +- 仅为人类读者提供的导航提示 +- 仅应保留在源文件中的内部注释 ### 示例 -Fern 自己的 [docs 快速开始](https://github.com/fern-api/docs/blob/main/fern/products/docs/pages/getting-started/quickstart.mdx) 将 GitHub UI 点击步骤与其 CLI 等效操作配对： +Fern 自己的[文档快速开始](https://github.com/fern-api/docs/blob/main/fern/products/docs/pages/getting-started/quickstart.mdx)将 GitHub UI 点击步骤与其 CLI 等价形式配对： ````jsx quickstart.mdx wordWrap 使用 `fern-api/docs-starter` 仓库作为您站点的模板： @@ -38,18 +37,18 @@ Fern 自己的 [docs 快速开始](https://github.com/fern-api/docs/blob/main/fe 1. 导航到 [fern-api/docs-starter](https://github.com/fern-api/docs-starter) 并点击 **Use this template** 按钮（位于此页面右上角）。您必须登录 GitHub。 2. 选择 **create a new repository** 选项。将其命名为 `fern-docs`。 -3. 克隆您新创建的仓库并在您喜欢的代码编辑器中打开它（例如，Cursor、VS Code）。 +3. 克隆您新创建的仓库并在您喜欢的代码编辑器中打开它（例如 Cursor、VS Code）。 -使用 GitHub CLI 从模板创建新仓库并在本地克隆它： +Use the GitHub CLI to create a new repository from the template and clone it locally: ```bash gh repo create my-org/fern-docs --template fern-api/docs-starter --private --clone cd fern-docs ``` -将 `my-org/fern-docs` 替换为您期望的所有者和仓库名称。如果您想要公共仓库，请使用 `--public` 而不是 `--private`。 +Replace `my-org/fern-docs` with your desired owner and repository name. Use `--public` instead of `--private` if you want a public repository. ```` @@ -60,33 +59,33 @@ cd fern-docs 1. 导航到 [fern-api/docs-starter](https://github.com/fern-api/docs-starter) 并点击 **Use this template** 按钮（位于此页面右上角）。您必须登录 GitHub。 2. 选择 **create a new repository** 选项。将其命名为 `fern-docs`。 - 3. 克隆您新创建的仓库并在您喜欢的代码编辑器中打开它（例如，Cursor、VS Code）。 + 3. 克隆您新创建的仓库并在您喜欢的代码编辑器中打开它（例如 Cursor、VS Code）。 - 使用 GitHub CLI 从模板创建新仓库并在本地克隆它： + Use the GitHub CLI to create a new repository from the template and clone it locally: ```bash gh repo create my-org/fern-docs --template fern-api/docs-starter --private --clone cd fern-docs ``` - 将 `my-org/fern-docs` 替换为您期望的所有者和仓库名称。如果您想要公共仓库，请使用 `--public` 而不是 `--private`。 + Replace `my-org/fern-docs` with your desired owner and repository name. Use `--public` instead of `--private` if you want a public repository. -在文档站点上，人类读者只能看到编号的 UI 步骤 —— `` 块被隐藏。读取此页面 Markdown 输出的 LLM 看到的相反：没有 UI 步骤，只有它们可以实际运行的 `gh repo create` 命令。每个受众都得到他们可以执行的路径。 +在文档站点上，人类读者只看到编号的 UI 步骤——`` 块是隐藏的。读取此页面 Markdown 输出的 LLM 看到的相反：没有 UI 步骤，只有它们可以实际运行的 `gh repo create` 命令。每个受众都获得他们可以执行的路径。 -指导原则：**仅 UI 元素属于人类读者，而它们的程序化等效操作属于 AI 代理。** 将可点击的卡片和 UI 演练包装在 `` 中，这样代理会跳过它们，并为每个 UI 步骤配对一个 `` 块，提供 CLI 或 API 等效操作。 +指导原则：**仅限 UI 的元素属于人类读者，而它们的程序化等价物属于 AI 代理。** 将可点击的卡片和 UI 演练包装在 `` 中，以便代理跳过它们，并为每个 UI 步骤配对一个 `` 块，给出 CLI 或 API 等价物。 -要预览和调试 AI 在任何页面上看到的内容，您可以在页面 URL 后添加 `.md` 或 `.mdx` 来[查看其 Markdown 源文件](/learn/docs/developer-tools/view-markdown)。 +要预览和调试 AI 为任何页面看到的内容，您可以在页面 URL 后附加 `.md` 或 `.mdx` 来[查看其 Markdown 源文件](/learn/docs/ai-features/markdown)。 ## 过滤端点输出 -使用 `lang` 和 `excludeSpec` 查询参数过滤 `llms.txt` 和 `llms-full.txt` 输出以减少令牌使用量。参数也可以组合使用。 +使用 `lang` 和 `excludeSpec` 查询参数过滤 `llms.txt` 和 `llms-full.txt` 输出，以减少令牌使用量。参数也可以组合使用。 -```txt Example +```txt 示例 /llms.txt?lang=python /llms-full.txt?excludeSpec=true /llms-full.txt?lang=python&excludeSpec=true @@ -102,7 +101,7 @@ cd fern-docs ## 排除整个页面 -您可以通过[在页面的 frontmatter 中添加 `noindex: true`](/learn/docs/seo/setting-seo-metadata#noindex) 来从 LLM 端点（`llms.txt` 和 `llms-full.txt`）中排除整个页面。标记为 `noindex` 的页面不会被搜索引擎索引，但在您的侧边栏导航中保持可见，仍然可以通过 URL 直接访问。要同时从导航中隐藏页面，请参阅[隐藏内容](/learn/docs/customization/hiding-content)。 +您可以通过[在页面的 frontmatter 中添加 `noindex: true`](/learn/docs/seo/setting-seo-metadata#noindex) 来从 LLM 端点（`llms.txt` 和 `llms-full.txt`）排除整个页面。标记为 `noindex` 的页面不会被搜索引擎索引，但在您的侧边栏导航中仍然可见，并且仍可以通过 URL 直接访问。要同时从导航中隐藏页面，请参阅[隐藏内容](/learn/docs/customization/hiding-content)。 ```mdx docs/pages/internal-notes.mdx --- @@ -113,7 +112,7 @@ noindex: true ## 提供自定义文件 -要提供您自己的 `llms.txt` 或 `llms-full.txt` 而不是自动生成的版本，请在 [`docs.yml` 中的 `agents` 键](/learn/docs/configuration/site-level-settings#agents-configuration)下指向您的文件： +要提供您自己的 `llms.txt` 或 `llms-full.txt` 而不是自动生成的版本，请在 [`docs.yml` 中的 `agents` 键下](/learn/docs/configuration/site-level-settings#agents-configuration)指向您的文件： ```yaml docs.yml agents: @@ -121,6 +120,8 @@ agents: llms-full-txt: ./path/to/llms-full.txt ``` -路径相对于 `docs.yml` 文件。CLI 会验证每个文件是否存在，并将其作为文档部署的一部分上传。您的自定义文件在根级别的 `/llms.txt` 和 `/llms-full.txt` 端点提供服务。嵌套路径（例如，`/api-reference/llms.txt`）继续使用自动生成的输出。 +路径相对于 `docs.yml` 文件。CLI 验证每个文件是否存在并将其作为您的文档部署的一部分上传。您的自定义文件在根级别的 `/llms.txt` 和 `/llms-full.txt` 端点提供。嵌套路径（例如 `/api-reference/llms.txt`）继续使用自动生成的输出。 -您可以提供一个或两个文件。任何您未指定的文件都会回退到自动生成的版本。 \ No newline at end of file +您可以提供其中一个或两个文件。您未指定的任何文件都回退到自动生成的版本。 + +要控制*哪些*爬虫访问您的站点而不是*它们接收什么*，请改为提供[自定义 `robots.txt`](/learn/docs/seo/robots-txt)。 diff --git a/fern/translations/zh/products/docs/pages/ai/llms-txt/overview.mdx b/fern/translations/zh/products/docs/pages/ai/llms-txt/overview.mdx index 7c3d639b5..1870e0abc 100644 --- a/fern/translations/zh/products/docs/pages/ai/llms-txt/overview.mdx +++ b/fern/translations/zh/products/docs/pages/ai/llms-txt/overview.mdx @@ -1,12 +1,11 @@ --- title: "`llms.txt` 和 `llms-full.txt`" description: Fern 自动生成 llms.txt 和 llms-full.txt Markdown 文件，以便 AI 工具可以发现和索引您的文档。 -sidebar-title: '`llms.txt` 和 `llms-full.txt`' --- -[`llms.txt`](https://llmstxt.org/) 是一个向 AI 开发工具暴露网站内容的标准。Fern 实现了这个标准，自动生成和维护 `llms.txt` 和 `llms-full.txt` Markdown 文件，以便 AI 工具可以发现和索引您的文档。 +[`llms.txt`](https://llmstxt.org/) 是一个向 AI 开发者工具公开网站内容的标准。Fern 实现了这个标准，自动生成和维护 `llms.txt` 和 `llms-full.txt` Markdown 文件，以便 AI 工具可以发现和索引您的文档。对于单个页面，代理还可以[直接获取 Markdown](/learn/docs/ai-features/markdown)。 -Fern 还在任何页面 URL 上提供[干净的 Markdown 而不是 HTML](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation)，当请求包含 `Accept: text/markdown` 头时，确保代理只接收它们需要的内容。这些功能结合在一起可以减少 90% 以上的 token 消耗。 +`llms.txt` 和 `llms-full.txt` 是 Fern 为非人类消费者提供的根级文件，与 [`robots.txt`](/learn/docs/seo/robots-txt) 一起提供。`robots.txt` 决定哪些爬虫可以访问您的网站以及您广播什么 AI 训练信号；`llms.txt` 和 `llms-full.txt` 塑造 AI 代理一旦访问后会收到什么内容。 `llms.txt` 和 `llms-full.txt` 返回相同的格式： -```txt title=".../page/llms.txt and .../page/llms-full.txt" +```txt title=".../page/llms.txt 和 .../page/llms-full.txt" # Fern Docs -> Build beautiful documentation websites with Fern. +> 使用 Fern 构建精美的文档网站。 ``` -这两个文件不同： +这两个文件有所不同： ```txt title=".../section/llms.txt" -- [Fern Docs](https://example.com/docs): Build beautiful documentation websites with Fern. +- [Fern Docs](https://example.com/docs): 使用 Fern 构建精美的文档网站。 ``` ```txt title=".../section/llms-full.txt" # Fern Docs -> Build beautiful documentation websites with Fern. +> 使用 Fern 构建精美的文档网站。 ``` @@ -78,9 +77,9 @@ subtitle: Build beautiful documentation websites with Fern. - 配置默认指令，该指令会添加到每个提供给 AI 代理的页面前面。 + 配置预置到提供给 AI 代理的每个页面的默认指令。 - 跟踪 LLM 流量并向读者暴露 `llms.txt` 端点。 + 跟踪 LLM 流量并向读者展示 `llms.txt` 端点。 - \ No newline at end of file + diff --git a/fern/translations/zh/products/docs/pages/ai/writer.mdx b/fern/translations/zh/products/docs/pages/ai/writer.mdx index 990c96946..7d170b57b 100644 --- a/fern/translations/zh/products/docs/pages/ai/writer.mdx +++ b/fern/translations/zh/products/docs/pages/ai/writer.mdx @@ -1,57 +1,34 @@ --- title: Fern Writer -description: 基于 Slack 的技术写作代理，通过 GitHub 拉取请求更新您的文档 -sidebar-title: Fern Writer +description: 一个基于 Slack 的技术写作代理，通过 GitHub pull requests 更新您的文档 --- -Fern Writer 是一个基于 Slack 的技术写作代理，可在您的产品发展过程中保持文档同步。它由 [Cognition 的 Devin](https://cognition.ai/blog/introducing-devin) 驱动。Fern Writer 理解 Fern 组件和您的写作风格，并可通过文档仓库中的 `AGENTS.md` 文件进行自定义。 +Fern Writer 是一个基于 Slack 的技术写作代理，可在您的产品发展过程中保持文档同步。它由 [Cognition 的 Devin](https://cognition.ai/blog/introducing-devin) 提供支持。Fern Writer 理解 Fern 组件和您的写作风格，并可通过文档仓库中的 `AGENTS.md` 文件进行自定义。 - - Fern Writer in Slack - - -## 工作原理 - -### 发起请求 - -在您已添加 Fern Writer 的 Slack 频道中，标记 `@Fern Writer` 并描述您需要的更改。Fern Writer [仅在被直接标记时响应](#隐私和数据处理)。它会对您的消息进行表情反应以确认收到，然后创建拉取请求并回复链接。 - - - Fern Writer opening a PR - - -Fern Writer 支持图片和文件附件以提供额外的上下文。当在现有对话串中被标记时，它会读取完整对话以理解上下文后再响应。 - -| 用例 | 示例请求 | -|----------|----------------| -| 为新功能编写文档（基于拉取请求） | `@Fern Writer 为 PR #123 中添加的新速率限制功能编写文档` | -| 向现有页面添加新内容 | `@Fern Writer 在 webhook 指南中添加关于 webhook 重试行为的章节` | -| 重新组织和整合内容 | `@Fern Writer 合并身份验证和授权页面，并从旧的认证页面添加重定向` | -| 修复错误并提高清晰度 | `@Fern Writer 修复快速开始中损坏的代码示例，并将包版本更新到 v2.1.0` | - - + - + + +## 工作原理 + +### 提出请求 -### 审查和合并 +在您添加了 Fern Writer 的 Slack 频道中，标记 `@Fern Writer` 并描述您需要的更改。Fern Writer [只有在被直接标记时才会响应](#隐私和数据处理)。它会对您的消息做出反应以确认收到，然后创建一个 pull request 并回复链接。 -通过在 Slack 对话串中评论来请求更改。一旦 PR 满足您的要求，就像合并其他任何拉取请求一样合并它。 +Fern Writer 支持图片和文件附件以提供额外的上下文。当在现有线程中被标记时，它会阅读完整的对话以在响应前理解上下文。 -### 拉取请求归属 +### 审核和合并 + +通过在 Slack 线程中评论来请求更改。一旦 PR 满足您的要求，就像合并任何其他 pull request 一样合并它。 + +### Pull request 归属 -每个拉取请求在描述中都包含一个 **请求者** 字段，将更改归属于发起请求的人员或团队。提交已签名并归属于 `fern-support`，确保自动更改与您仓库历史记录中的手动贡献明确区分。 +每个 pull request 在描述中都包含一个**请求者**字段，将更改归属于发起请求的人员或团队。提交经过签名并归属于 `fern-support`，确保自动更改在您仓库的历史记录中与手动贡献明确区分。 + +## 示例请求 + + +@Fern Writer 记录 PR #123 中添加的新速率限制功能 + + +
+ + +@Fern Writer 在 webhooks 指南中添加关于 webhook 重试行为的部分 + + +
+ + +@Fern Writer 合并身份验证和授权页面，并从旧的认证页面添加重定向 + + +
+ + +@Fern Writer 修复快速开始中损坏的代码示例，并将包版本更新为 v2.1.0 + ## 设置 @@ -68,14 +69,14 @@ Fern Writer 支持图片和文件附件以提供额外的上下文。当在现 Fern Writer 仅支持 GitHub。不支持 GitLab 和其他 Git 提供商。 -要开始使用 Fern Writer，请将其添加到您的 Slack 工作区（您必须是 Slack 管理员）并将其邀请到您的团队讨论文档的频道中。 +要开始使用 Fern Writer，请将其添加到您的 Slack 工作空间（您必须是 Slack 管理员）并邀请它到您的团队讨论文档的频道。 - + -[获取您组织的专属 Slack 安装链接](/learn/docs/scribe-api/fern-writer-api/get-fern-writer-install-link)。提供： -- 您的 [Fern 令牌](/learn/cli-api-reference/cli-reference/commands#fern-token) -- 包含您文档的 GitHub 仓库，格式为 `owner/repo`（例如 `acme/docs`）。[Fern GitHub App](https://github.com/apps/fern-api) 必须安装在该仓库中。 +为您的组织[获取唯一的 Slack 安装链接](/learn/docs/scribe-api/fern-writer-api/get-fern-writer-install-link)。提供： +- 您的 [Fern token](/learn/cli-api-reference/cli-reference/commands#fern-token) +- 以 `owner/repo` 格式包含您文档的 GitHub 仓库（例如，`acme/docs`）。必须在仓库中安装 [Fern GitHub App](https://github.com/apps/fern-api)。 您也可以使用此 cURL 请求： ```bash @@ -84,11 +85,11 @@ curl -G https://fai.buildwithfern.com/scribe/slack/get-install \ --data-urlencode github_repo= ``` -访问响应中返回的 URL。 +跟随响应中返回的 URL。 - -您将被重定向到 Slack 以授权 Fern Writer。选择您想添加 Fern Writer 的工作区并点击 **允许**。 + +您将被重定向到 Slack 以授权 Fern Writer。选择您想要添加 Fern Writer 的工作空间并点击**允许**。 @@ -100,6 +101,6 @@ curl -G https://fai.buildwithfern.com/scribe/slack/get-install \ ## 隐私和数据处理 -Fern Writer 不会直接存储您的 Slack 消息。当您标记 `@Fern Writer` 或引用消息或对话串时，内容会存储在会话中以生成文档拉取请求。任务完成后不会保留会话数据。 +Fern Writer 不会直接存储您的 Slack 消息。当您标记 `@Fern Writer` 或引用消息或线程时，内容会存储在会话中以生成文档 pull request。任务完成后不会保留会话数据。 -无论是 Fern 还是 [Devin](https://docs.devin.ai/admin/security#how-is-your-data-used-to-improve-devin) 都不会使用您的数据来训练 AI 模型。Fern 明确配置其 Devin 集成以选择退出任何用于模型训练的数据收集。您的频道消息、代码和文档内容永远不会用于训练目的。有关其他详细信息，请参阅 Devin 关于 [Slack 集成安全性](https://docs.devin.ai/admin/security#integrating-with-slack) 的文档。 \ No newline at end of file +无论是 Fern 还是 [Devin](https://docs.devin.ai/admin/security#how-is-your-data-used-to-improve-devin) 都不会使用您的数据来训练 AI 模型。Fern 明确配置其 Devin 集成以选择退出模型训练的任何数据收集。您的频道消息、代码和文档内容永远不会用于训练目的。有关更多详细信息，请参阅 Devin 关于 [Slack 集成安全性](https://docs.devin.ai/admin/security#integrating-with-slack) 的文档。 diff --git a/fern/translations/zh/products/docs/pages/api-references/api-explorer.mdx b/fern/translations/zh/products/docs/pages/api-references/api-explorer.mdx index 0d70d4ffb..4a299cabf 100644 --- a/fern/translations/zh/products/docs/pages/api-references/api-explorer.mdx +++ b/fern/translations/zh/products/docs/pages/api-references/api-explorer.mdx @@ -1,70 +1,56 @@ --- -title: API 探索器 -subtitle: 通过允许用户直接在 API 参考文档中对您的 API 进行真实调用，来减少"获得 200 响应的时间"。 -sidebar-title: API 资源管理器 +title: API 浏览器 +subtitle: 通过允许用户直接在 API 参考文档中对您的 API 进行真实调用，减少"达到 200 响应的时间"。 --- -Fern 的 API 探索器允许用户在不离开文档的情况下对您的 API 发起经过身份验证的请求。 +Fern 的 API 浏览器允许用户在不离开文档的情况下对您的 API 进行身份验证请求。 ## 使用示例自动填充 -Fern 将自动使用 API 规范中设置的值填充端点的字段。 +Fern 将自动使用您的 API 规范中设置的值填充端点字段。

## 身份验证 -API 探索器支持在您的 OpenAPI 规范或 `generators.yml` 中配置的[所有身份验证方案](/learn/api-definitions/openapi/authentication)，包括多种身份验证方案。当有多种方案可用时，API 探索器会自动在下拉菜单中显示它们，允许用户在发送请求之前选择并配置其首选的身份验证方法。 +API 浏览器支持在您的 OpenAPI 规范或 `generators.yml` 中配置的[所有身份验证方案](/learn/api-definitions/openapi/authentication)，包括多种身份验证方案。当有多种方案可用时，API 浏览器会自动在下拉菜单中显示它们，允许用户在发送请求之前选择和配置他们首选的身份验证方法。 -一旦用户设置了身份验证凭据，他们的凭据将在整个探索会话期间保持不变。 +一旦用户设置了身份验证凭据，他们的凭据将在整个探索会话中持续有效。
-身份验证凭据仅使用 cookie 存储在客户端。不会收集或存储任何敏感的用户信息。 +身份验证凭据仅使用 cookie 在客户端存储。不会收集或存储敏感的用户信息。 要为已登录用户自动填充 API 密钥，请参阅 [API 密钥注入](/learn/docs/authentication/features/api-key-injection)。 ## 多环境 -当在 [OpenAPI](/learn/api-definitions/openapi/extensions/server-names-and-url-templating) 或 [Fern Definition](/learn/api-definitions/ferndef/api-yml/environments) 中配置了多个服务器 URL 时，用户可以从 API 探索器的下拉菜单中在不同环境（例如，生产环境和沙盒环境）之间切换。所选环境在他们在页面之间导航时保持不变。 +当在 [OpenAPI](/learn/api-definitions/openapi/extensions/server-names-and-url-templating) 中配置了多个服务器 URL 时，用户可以通过 API 浏览器中的下拉菜单在环境之间切换（例如，生产环境和沙箱环境）。所选环境在用户在页面间导航时保持不变。
-用户还可以双击服务器 URL 手动编辑它，允许快速测试自定义环境或端点。 - -这是配置了多个服务器名称的 [Flagright 文档网站](https://docs.flagright.com/framl-api/api-reference/api-reference/transactions/get) 示例。 - - - - - ```yaml - openapi: 3.0.0 - servers: - - url: https://sandbox.api.flagright.com - x-fern-server-name: Sandbox API server (eu-1) - - url: https://sandbox-asia-1.api.flagright.com - x-fern-server-name: Sandbox API server (asia-1) - ``` - - - - - ```yaml - environments: - Sandbox API server (eu-1): https://sandbox.api.flagright.com - Sandbox API server (asia-1): https://sandbox-asia-1.api.flagright.com - ``` - - - - -## WebSocket Playground - -对于支持 WebSocket 连接的 API，API 探索器包含一个 **WebSocket** 特定的 Playground。WebSocket Playground 还允许用户与 API 建立连接，并实时发送/接收消息。 +用户还可以双击服务器 URL 来手动编辑它，允许快速测试自定义环境或端点。 + +这里是配置了多个服务器名称的 [Flagright 文档站点](https://docs.flagright.com/framl-api/api-reference/api-reference/transactions/get) 示例。 + + +```yaml +openapi: 3.0.0 +servers: + - url: https://sandbox.api.flagright.com + x-fern-server-name: Sandbox API server (eu-1) + - url: https://sandbox-asia-1.api.flagright.com + x-fern-server-name: Sandbox API server (asia-1) +``` + + +## WebSocket 演练场 + +对于支持 WebSocket 连接的 API，API 浏览器包含了 **WebSocket** 专用演练场。WebSocket 演练场还允许用户与 API 建立连接，并实时发送/接收消息。
-## 控制 API 探索器可用性 +## 控制 API 浏览器可用性 -对于 OpenAPI 规范，API 探索器默认为所有端点启用。您可以使用 [`x-fern-explorer`](/learn/api-definitions/openapi/extensions/api-explorer-control) 扩展全局或按端点禁用它。这通常用于禁用破坏性操作、支付处理或仅限管理员端点的探索器。 \ No newline at end of file +对于 OpenAPI 规范，API 浏览器默认为所有端点启用。您可以使用 [`x-fern-explorer`](/learn/api-definitions/openapi/extensions/api-explorer-control) 扩展全局或按端点禁用它。这通常用于禁用破坏性操作、支付处理或仅限管理员端点的浏览器。 diff --git a/fern/translations/zh/products/docs/pages/api-references/api-ref-content.mdx b/fern/translations/zh/products/docs/pages/api-references/api-ref-content.mdx index dc7502a48..5ad421e60 100644 --- a/fern/translations/zh/products/docs/pages/api-references/api-ref-content.mdx +++ b/fern/translations/zh/products/docs/pages/api-references/api-ref-content.mdx @@ -1,20 +1,17 @@ --- -title: 在 API Reference 中编写 Markdown 内容 -description: 在 API 文档中编写丰富的 Markdown 内容。为端点添加描述，创建摘要页面，并自定义您的 API Reference 布局。 -sidebar-title: 在 API 参考中编写 Markdown 内容 +title: 在 API 参考中编写 Markdown 内容 +description: 在 API 文档中编写丰富的 Markdown 内容。为端点添加描述，创建概览页面，并自定义 API 参考布局。 --- -Fern Docs 允许您在 API Reference 文档中编写 Markdown 内容。此功能对于为 API 端点提供额外的上下文、示例或说明非常有用。 +Fern Docs 允许您在 API 参考文档中编写 Markdown 内容。此功能对于为 API 端点提供额外的上下文、示例或解释非常有用。 -## 为端点添加 Markdown 内容 +## 向端点添加 Markdown 内容 -您可以使用 `description` 字段（OpenAPI）或 `docs` 字段（Fern Definition）在 API 定义中包含 Markdown 内容。这包括标注、代码块和[其他组件](/learn/docs/writing-content/components/overview)。 +您可以在 OpenAPI 的 API 定义中使用 `description` 字段来包含 Markdown 内容。这包括标注、代码块和[其他组件](/learn/docs/writing-content/components/overview)。 -您还可以使用 `