Make Generate [x] Reference pages consistent and consolidate layout docs #3656
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -96,28 +96,15 @@ The `layout` option allows you to specify the order of sub-packages, sections, e | |
| ``` | ||
| </Tab> | ||
| <Tab title="GraphQL"> | ||
| Reference individual GraphQL operations using the `operation` keyword with the format `OPERATION_TYPE operationName`, where `OPERATION_TYPE` is `QUERY`, `MUTATION`, or `SUBSCRIPTION`. If your schema includes operations that share the same name across different namespaces, use dot notation to disambiguate. | ||
| ```yaml title="docs.yml" | ||
| navigation: | ||
| - api: API Reference | ||
| layout: | ||
| - user: | ||
| - operation: QUERY admin.getUser | ||
| - operation: MUTATION createPlant | ||
| - operation: SUBSCRIPTION plantUpdates | ||
| </Tab> | ||
| </Tabs> | ||
|
|
||
|
|
@@ -132,24 +119,57 @@ The `layout` option allows you to specify the order of sub-packages, sections, e | |
| By default, section display names come from [service file names](/api-definitions/ferndef/endpoints/overview#service-definition) (Fern | ||
| Definition) or tag names (OpenAPI) in your spec. | ||
|
|
||
| To override the display name of a section, use the `section` property in your `docs.yml`. | ||
|
|
||
| <Tabs> | ||
| <Tab title="OpenAPI"> | ||
| ```yaml title="docs.yml" {4-6} | ||
| navigation: | ||
| - api: API Reference | ||
| layout: | ||
| - section: "Billing" # New section display name | ||
| referenced-packages: | ||
| - billing # lowerCamelCase version of original tag name from your spec | ||
| contents: [] | ||
| - section: "Bank Accounts" | ||
| referenced-packages: | ||
| - bankAccounts | ||
| contents: [] | ||
| ``` | ||
| <Note> | ||
| You can alternatively customize tag display names directly in your spec (or overlays file) using the [`x-displayName` extension](/api-definitions/openapi/extensions/tag-display-names). | ||
| </Note> | ||
| </Tab> | ||
| <Tab title="Fern Definition"> | ||
| ```yaml title="docs.yml" {4-6} | ||
| navigation: | ||
| - api: API Reference | ||
| layout: | ||
| - section: "Billing" # New section display name | ||
| referenced-packages: | ||
| - billing # lowerCamelCase version of original service file name from your spec | ||
| contents: [] | ||
| - section: "Bank Accounts" | ||
| referenced-packages: | ||
| - bankAccounts | ||
| contents: [] | ||
| ``` | ||
| </Tab> | ||
| <Tab title="GraphQL"> | ||
| ```yaml title="docs.yml" | ||
| navigation: | ||
| - api: GraphQL API Reference | ||
| layout: | ||
| - section: Plants | ||
| contents: | ||
| - operation: QUERY getPlant | ||
| - operation: MUTATION createPlant | ||
| - section: Real-time | ||
| contents: | ||
| - operation: SUBSCRIPTION plantUpdates | ||
| ``` | ||
| </Tab> | ||
| </Tabs> | ||
|
|
||
| ### Flattening sections | ||
|
|
||
|
|
@@ -205,6 +225,17 @@ To customize the display of an endpoint, you can add a `title`. You can also use | |
| slug: live-updates | ||
| ``` | ||
| </Tab> | ||
| <Tab title="GraphQL"> | ||
| ```yaml title="docs.yml" {6-8} | ||
| navigation: | ||
| - api: API Reference | ||
| layout: | ||
| - user: | ||
| - operation: QUERY getUser | ||
| title: Get user details | ||
| slug: get-user | ||
| ``` | ||
| </Tab> | ||
| </Tabs> | ||
|
|
||
| <Frame> | ||
|
|
@@ -252,6 +283,15 @@ You can hide an endpoint from the API Reference by setting `hidden` to `true`. T | |
| hidden: true | ||
| ``` | ||
| </Tab> | ||
| <Tab title="GraphQL"> | ||
| ```yaml title="docs.yml" {5} | ||
| navigation: | ||
| - api: API Reference | ||
| layout: | ||
| - operation: MUTATION deletePlant | ||
| hidden: true | ||
| ``` | ||
| </Tab> | ||
| </Tabs> | ||
|
|
||
| ### Adding custom sections | ||
|
|
@@ -274,16 +314,30 @@ You can add arbitrary folders in the sidebar by adding a `section` to your API R | |
| </Tab> | ||
| <Tab title="Fern Definition"> | ||
| ```yaml title="docs.yml" | ||
| navigation: | ||
| - api: API Reference | ||
| layout: | ||
| - section: My Section | ||
| icon: flower | ||
| contents: | ||
| - user.update | ||
| - plant | ||
| ``` | ||
| </Tab> | ||
| <Tab title="GraphQL"> | ||
| ```yaml title="docs.yml" | ||
| navigation: | ||
| - api: API Reference | ||
| layout: | ||
| - section: Plants | ||
| contents: | ||
| - operation: QUERY getPlant | ||
|
Contributor
There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶 |
||
| - operation: MUTATION createPlant | ||
| - section: Real-time | ||
| contents: | ||
| - operation: SUBSCRIPTION plantUpdates | ||
| ``` | ||
| </Tab> | ||
| </Tabs> | ||
|
|
||
| <Frame> | ||
|
|
@@ -360,7 +414,19 @@ navigation: | |
|
|
||
| When you set availability for a section, all endpoints in that section will inherit the section-level availability unless explicitly overridden in your API definition. | ||
|
|
||
| <Warning> | ||
| You can't set availability for individual OpenAPI and Fern Definition endpoints in `docs.yml` — endpoint availability must be configured directly in your API definition. Learn more about availability for [OpenAPI](/learn/api-definitions/openapi/extensions/availability) or [Fern Definition](/learn/api-definitions/ferndef/availability). | ||
|
|
||
| For GraphQL, `availability` can be set per operation: | ||
|
|
||
| ```yaml title="docs.yml" | ||
| navigation: | ||
| - api: API Reference | ||
| layout: | ||
| - operation: SUBSCRIPTION plantUpdates | ||
| availability: beta | ||
| ``` | ||
| </Warning> | ||
|
|
||
| ### Displaying endpoint errors | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'QUERY' has no definition.