diff --git a/fern/products/docs/pages/api-references/customize-api-ref.mdx b/fern/products/docs/pages/api-references/customize-api-ref.mdx index 0b6171e27..24efcf6cc 100644 --- a/fern/products/docs/pages/api-references/customize-api-ref.mdx +++ b/fern/products/docs/pages/api-references/customize-api-ref.mdx @@ -1,162 +1,75 @@ --- title: Customize API Reference layout -description: Customize your API Reference layout with Fern. Configure options, order sections and endpoints, flatten navigation, hide endpoints, display errors, and add custom content. +description: Reference for all configuration options available when customizing your API Reference layout in docs.yml. +max-toc-depth: 2 --- -When you [include an API in your `docs.yml` file](/learn/docs/api-references/generate-api-ref), you can customize how the endpoints and sections are displayed in the sidebar navigation. By default, the reference will generate a navigation hierarchy based on the structure of the API spec, but several customizations can be configured. +When you [include an API in your `docs.yml` file](/learn/docs/api-references/generate-api-ref), you can customize how the endpoints and sections are displayed in the sidebar navigation. By default, the reference generates a navigation hierarchy based on the structure of the API spec, but several customizations can be configured. - -If you are using an OpenAPI specification, sections are created based on the `tags` property, converted to `lowerCamelCase` convention (e.g., createUser). If you are using a Fern Definition, sections are created based on the [`service`](/learn/api-definition/fern/endpoints#service-definition) file names. - +For type-specific layout examples (endpoint referencing syntax, grouping into sections), see the individual reference pages: -If you would like to only display a subset of endpoints, read more about the Audiences property for [OpenAPI specifications](/learn/api-definitions/openapi/extensions/audiences) or [Fern Definitions](/learn/api-definition/fern/audiences). +- [REST API](/learn/docs/api-references/generate-api-ref#customize-the-layout) +- [GraphQL](/learn/docs/api-references/generate-graphql-ref#customize-the-layout) +- [WebSocket](/learn/docs/api-references/generate-websocket-ref#customize-the-layout) +- [OpenRPC](/learn/docs/api-references/generate-openrpc-ref#customize-the-layout) +- [Webhook](/learn/docs/api-references/generate-webhook-reference#customize-the-layout) -## Ordering the API Reference +To display only a subset of endpoints, see the Audiences property for [OpenAPI specifications](/learn/api-definitions/openapi/extensions/audiences) or [Fern Definitions](/learn/api-definition/fern/audiences). -### Alphabetizing endpoints and sections +## Alphabetizing endpoints and sections To sort all sections and endpoints alphabetically, unless explicitly ordered in `layout`, set `alphabetized` to `true`. ```yaml title="docs.yml" -navigation: +navigation: - api: API Reference alphabetized: true ``` -### Ordering top-level sections - -The `layout` option allows you to specify the order of sub-packages, sections, endpoints, and pages at the top level of your API Reference. - - - - ```yaml title="docs.yml" - navigation: - - api: API Reference - layout: - - POST /user - - user - - store - - plant - ``` - - - ```yaml title="docs.yml" - navigation: - - api: API Reference - layout: - - user.create - - user - - store - - plant - ``` - - - - -Ordered API Reference - +## Paginating endpoints -### Ordering section contents - - - - You can reference an endpoint using the format `METHOD /path`. - ```yaml title="docs.yml" - navigation: - - api: API Reference - layout: - - user: - - POST /user - - PUT /user/{username} - - DELETE /user/{username} - ``` - - - You can reference an endpoint using the format `serviceName.endpointName`. - ```yaml title="docs.yml" - navigation: - - api: API Reference - layout: - - user: - - user.create - - user.update - - user.delete - ``` - - - You can reference a WebSocket endpoint using the format `WSS /path/name`. - ```yaml title="docs.yml" - navigation: - - api: API Reference - layout: - - plants: - - GET /plants - - WSS /plants/live-updates - - WSS /plants/growth-monitor - ``` - - - You can reference an operation using the format `operation: OPERATION_TYPE operationName`. See [GraphQL layout customization](/learn/docs/api-references/generate-graphql-ref#customize-the-layout) for more details. - ```yaml title="docs.yml" - navigation: - - api: API Reference - layout: - - user: - - operation: QUERY getUser - - operation: MUTATION createUser - - operation: MUTATION deleteUser - ``` - - - You can reference a WebSocket endpoint using the format `WSS /path/name`. - ```yaml title="docs.yml" - navigation: - - api: API Reference - layout: - - plants: - - GET /plants - - WSS /plants/live-updates - - WSS /plants/growth-monitor - ``` - - +By default, all endpoints are displayed on a single long page. To display each endpoint on its own page, set `paginated` to `true`. - -Content ordered in the API Reference - +```yaml title="docs.yml" +navigation: + - api: API Reference + paginated: true +``` -## Customizing the API Reference +## Renaming sections -### Renaming sections +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. -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. + +If you are using an OpenAPI specification, sections are created based on the `tags` property, converted to `lowerCamelCase` convention (e.g., createUser). If you are using a Fern Definition, sections are created based on the [`service`](/learn/api-definition/fern/endpoints#service-definition) file names. + -To override the display name of a section, use the `section` property in your `docs.yml` and reference the `lowerCamelCase` version of the original service file name (Fern Definition) or tag name (OpenAPI) in `referenced-packages`. +To override the display name, use the `section` property with `referenced-packages` to map to the original tag or service file name in `lowerCamelCase`: ```yaml title="docs.yml" {4-6} -navigation: +navigation: - api: API Reference layout: - section: "Billing" # New section display name - referenced-packages: + referenced-packages: - billing # lowerCamelCase version of original tag/service file name from your spec contents: [] - section: "Bank Accounts" - referenced-packages: + referenced-packages: - bankAccounts contents: [] ``` + - For OpenAPI, you can alternatively customize tag display names directly in your spec (or `overrides.yml` file) using the [`x-displayName` extension](/api-definitions/openapi/extensions/tag-display-names). + For OpenAPI, you can alternatively customize tag display names directly in your spec (or `overrides.yml` file) using the [`x-displayName` extension](/api-definitions/openapi/extensions/tag-display-names). -### Flattening sections +## Flattening sections -To remove the API Reference title and display the section contents, set `flattened` to `true`. +To remove the API Reference title and display the section contents at the top level, set `flattened` to `true`. ```yaml title="docs.yml" -navigation: +navigation: - api: API Reference flattened: true ``` @@ -165,132 +78,7 @@ navigation: Flattened API Reference -### Styling endpoints - -To customize the display of an endpoint, you can add a `title`. You can also use `slug` to customize the endpoint URL. - - - - ```yaml title="docs.yml" {6-7} - navigation: - - api: API Reference - layout: - - user: - - endpoint: POST /user - title: Create a User - slug: user-creation - - DELETE /user/{username} - ``` - - - ```yaml title="docs.yml" {6-7} - navigation: - - api: API Reference - layout: - - user: - - endpoint: user.create - title: Create a User - slug: user-creation - - user.delete - ``` - - - ```yaml title="docs.yml" {5-7} - navigation: - - api: API Reference - layout: - - plants: - - endpoint: WSS /plants/live-updates - title: Live plant updates - slug: live-updates - ``` - - - - -Setting an endpoint title - - -### Hiding endpoints - -You can hide an endpoint from the API Reference by setting `hidden` to `true`. The endpoint will still be accessible at its URL. - - - - ```yaml title="docs.yml" {10} - navigation: - - api: API Reference - layout: - - user: - - endpoint: POST /user - title: Create a User - slug: user-creation - - endpoint: DELETE /user/{username} - hidden: true - ``` - - - ```yaml title="docs.yml" {10} - navigation: - - api: API Reference - layout: - - user: - - endpoint: user.create - title: Create a User - slug: user-creation - - endpoint: user.delete - hidden: true - ``` - - - ```yaml title="docs.yml" {6} - navigation: - - api: API Reference - layout: - - plants: - - endpoint: WSS /plants/live-updates - hidden: true - ``` - - - -### Adding custom sections - -You can add arbitrary folders in the sidebar by adding a `section` to your API Reference layout. A section can comprise entire groups of endpoints, individual endpoints, or even just Markdown pages. Sections can be customized by adding properties like a `icon`, `summary`, `slug` (or `skip-slug`), `availability`, and `contents`. - - - - ```yaml title="docs.yml" - navigation: - - api: API Reference - layout: - - section: My Section - icon: flower - contents: - - PUT /user/{username} - - plant - - plantInfo # tag names are converted to camelCase convention - ``` - - - ```yaml title="docs.yml" - navigation: - - api: API Reference - layout: - - section: My Section - icon: flower - contents: - - user.update - - plant - ``` - - - - -Custom section in the API Reference - - -### Adding a section overview +## Adding a section overview You can add overview pages to your API Reference or individual sections in two ways: @@ -326,43 +114,43 @@ You can add overview pages to your API Reference or individual sections in two w API Reference with a summary page -### Adding pages and links +## Adding pages and links -You can add regular pages and external links within your API Reference. +You can add regular pages and external links within your API Reference. ```yaml title="docs.yml" -navigation: +navigation: - api: API Reference - layout: - - user: - contents: + layout: + - user: + contents: - page: User Guide path: ./docs/pages/user-guide.mdx - link: Link Title href: http://google.com ``` -### Adding availability +## Adding availability -You can set the availability for the entire API Reference or for specific sections. Options are: `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, or `beta`. +You can set the availability for the entire API Reference or for specific sections. Options are: `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, or `beta`. ```yaml title="docs.yml" {3, 6} -navigation: +navigation: - api: API Reference availability: generally-available - layout: + layout: - section: My Section availability: beta icon: flower - contents: + contents: # endpoints here ``` 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. - + You can't set availability for individual 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). -### Displaying endpoint errors +## Displaying endpoint errors Set `display-errors` to `true` to show error schemas on endpoint pages. The error names, status codes, and response objects are pulled from your API definition. @@ -382,76 +170,146 @@ Clicking on an error expands it to show the error name, code, and object returne ![Endpoint errors when expanded](https://fern-image-hosting.s3.amazonaws.com/fern/errors-expanded.png) -## Configuration options reference +## API-level property reference -The following properties can be set on the `- api` entry in your `docs.yml` navigation. - - - When `true`, organizes all sections and endpoints in alphabetical order. - - +The following properties can be set on the `- api:` entry in your `docs.yml` navigation. Title of the API Reference section. + + + Only used when your project has [multiple APIs](/learn/docs/api-references/generate-api-ref#include-more-than-one-api-reference). The value must match the folder name containing the API definition. Don't set this property if you only have a single API. - - List of [audiences](/learn/docs/api-references/audiences) that determines which endpoints, schemas, and properties are displayed in your API Reference. + + Organizes all sections and endpoints in alphabetical order, unless explicitly ordered in `layout`. + + + List of [audiences](/learn/docs/api-references/audiences) that determines which endpoints, schemas, and properties are displayed. - Set the [availability status](#adding-availability) for the entire API Reference or specific sections. - + Set the availability status for the entire API Reference. Options: `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, `beta`. - Displays [error schemas](#displaying-endpoint-errors) on endpoint pages of your API Reference. - + Displays error schemas on endpoint pages. - Displays all endpoints at the top level and hides the API Reference section title. - + Removes the API Reference title and displays sections at the top level. Icon to display next to the API section in the navigation. - - Customize the order that your API endpoints are displayed in the docs site. See [Ordering the API Reference](#ordering-the-api-reference) for details. - + Customize the order and grouping of endpoints in the sidebar. Accepts [endpoint references](#endpoint-properties), [sections](#section-properties), [pages, and links](#page-and-link-properties). - Displays all endpoints on separate pages. By default, endpoints are displayed on one single, long page. - + Displays endpoints on separate pages instead of a single long page. - When `true`, skips slug generation for the API section. + Skips slug generation for the API section. + + + Custom slug for the API section. + + + + Relative path to a Markdown file displayed at the top of the API section. + + + + Uses OpenAPI tag descriptions as summary pages for each section. OpenAPI only. + + +## Endpoint property reference + +Properties available when referencing an endpoint or operation in `layout`. + + + Reference an endpoint. Format varies by API type: `METHOD /path` (REST), `WSS /path` (WebSocket), `methodName` (OpenRPC), `subpackage_{tag}.{eventName}` (Webhook). + + + + Reference a GraphQL operation. Format: `OPERATION_TYPE operationName` where type is `QUERY`, `MUTATION`, or `SUBSCRIPTION`. + + + + Custom display name for the endpoint or operation. - Customize the slug for the API section. By default, the slug is generated from the API title. + Custom URL slug for the endpoint or operation. + + + + Hides the endpoint from the sidebar. The page remains accessible via its URL. + + + + Set the availability status for an individual endpoint or operation. + + +## Section property reference +Properties available when defining a custom section in `layout`. + + + Display name for the section. + + + + Endpoints, operations, sub-sections, pages, or links within the section. + + + + Maps the section to original tag names (OpenAPI) or service file names (Fern Definition) to inherit their endpoints. + + + + Icon for the section. - Relative path to a Markdown file displayed at the top of the API section. + Path to a Markdown file displayed as the section overview. + + + Availability status for the section. Inherited by all endpoints unless overridden in the API definition. - - When `true`, uses OpenAPI tag descriptions as summary pages for each section. + + Custom URL slug for the section. + + + Skip slug generation for the section. - - Only used when your project has [multiple APIs](/learn/docs/api-references/generate-api-ref#include-more-than-one-api-reference). The value must match the folder name containing the API definition. Do not set this property if you only have a single API, as it will cause errors. +## Page and link property reference + +Include Markdown pages and external links in `layout`. + + + Title of the page to display in the sidebar. + + + + Relative path to the Markdown file. + + + + Title of the external link to display in the sidebar. + + + URL for the link. diff --git a/fern/products/docs/pages/api-references/generate-api-ref.mdx b/fern/products/docs/pages/api-references/generate-api-ref.mdx index 65037ce2a..e6272986c 100644 --- a/fern/products/docs/pages/api-references/generate-api-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-api-ref.mdx @@ -39,7 +39,81 @@ Fern will automatically populate your endpoints, types, and code snippets from y -For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). +## Customize the layout + +Use the `layout` property in `docs.yml` to control how endpoints appear in the sidebar. Reference individual endpoints with the `endpoint` keyword using the format `METHOD /path` (OpenAPI) or `serviceName.endpointName` (Fern Definition). + +You can also set a custom `title`, `slug`, `hidden`, or `availability` on each endpoint: + + + +```yaml title="docs.yml" +navigation: + - api: API Reference + layout: + - endpoint: POST /plants + title: Create a plant + slug: create-plant + - endpoint: GET /plants/{plantId} + title: Get plant details + - endpoint: DELETE /plants/{plantId} + hidden: true +``` + + +```yaml title="docs.yml" +navigation: + - api: API Reference + layout: + - endpoint: plants.create + title: Create a plant + slug: create-plant + - endpoint: plants.get + title: Get plant details + - endpoint: plants.delete + hidden: true +``` + + + +### Group endpoints into sections + +Organize endpoints under custom sections: + + + +```yaml title="docs.yml" +navigation: + - api: API Reference + layout: + - section: Plants + contents: + - POST /plants + - GET /plants/{plantId} + - section: Gardens + contents: + - GET /gardens +``` + + +```yaml title="docs.yml" +navigation: + - api: API Reference + layout: + - section: Plants + contents: + - plants.create + - plants.get + - section: Gardens + contents: + - gardens.list +``` + + + + +For shared layout options like renaming sections, adding pages and links, availability, and more, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). + ### Include more than one API Reference diff --git a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx index 79d72c077..63dc416e0 100644 --- a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx @@ -124,5 +124,5 @@ navigation: ``` -For the full set of layout options that apply to all API types (alphabetizing, flattening, adding pages and links, and more), see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). +For shared layout options like renaming sections, adding pages and links, availability, and more, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). diff --git a/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx b/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx index 903b451c3..cd1188974 100644 --- a/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx @@ -26,4 +26,45 @@ Fern generates OpenRPC Reference documentation from an [OpenRPC](https://open-rp Path to your OpenRPC specification file. You can include multiple OpenRPC specs if your project exposes more than one JSON-RPC API. - \ No newline at end of file + + +## Customize the layout + +Use the `layout` property in `docs.yml` to control how JSON-RPC methods appear in the sidebar. Reference individual methods with the `endpoint` keyword using the method name from your OpenRPC spec. + +You can also set a custom `title`, `slug`, `hidden`, or `availability` on each method: + +```yaml title="docs.yml" +navigation: + - api: JSON-RPC API Reference + layout: + - endpoint: getPlantByName + title: Get plant by name + slug: get-plant + - endpoint: listPlants + title: List all plants + - endpoint: deletePlant + hidden: true +``` + +### Group methods into sections + +Organize methods under custom sections: + +```yaml title="docs.yml" +navigation: + - api: JSON-RPC API Reference + layout: + - section: Plants + contents: + - getPlantByName + - listPlants + - section: Gardens + contents: + - getGarden + - createGarden +``` + + +For shared layout options like renaming sections, adding pages and links, availability, and more, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). + diff --git a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx index 59a6f19ec..d11a29573 100644 --- a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx @@ -111,6 +111,46 @@ When using multiple webhook definitions, organize them in separate directories w +## Customize the layout + +Use the `layout` property in `docs.yml` to control how webhooks appear in the sidebar. Reference individual webhook events using the `endpoint` keyword with the format `subpackage_{tag}.{webhook-event-name}` (OpenAPI) or `subpackage_{name}.{webhook-event-name}` (Fern Definition). + +You can also set a custom `title`, `slug`, `hidden`, or `availability` on each webhook: + +```yaml title="docs.yml" +navigation: + - api: Webhook Reference + api-name: webhooks-v1 + layout: + - endpoint: subpackage_plants.newPlantWebhook + title: New plant created + slug: new-plant + - endpoint: subpackage_plants.plantUpdatedWebhook + hidden: true +``` + +### Group webhooks into sections + +Organize webhooks under custom sections: + +```yaml title="docs.yml" +navigation: + - api: Webhook Reference + api-name: webhooks-v1 + layout: + - section: Plant events + contents: + - subpackage_plants.newPlantWebhook + - subpackage_plants.plantUpdatedWebhook + - section: Order events + contents: + - subpackage_orders.orderCreatedWebhook +``` + + +For shared layout options like renaming sections, adding pages and links, availability, and more, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). + + ### Create individual documentation pages for each webhook event To display each webhook event as an individual page with rich examples: diff --git a/fern/products/docs/pages/api-references/generate-websocket-ref.mdx b/fern/products/docs/pages/api-references/generate-websocket-ref.mdx index 2283c4732..9344dbcef 100644 --- a/fern/products/docs/pages/api-references/generate-websocket-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-websocket-ref.mdx @@ -27,19 +27,38 @@ Fern generates WebSocket Reference documentation from an [AsyncAPI specification Fern Definition WebSocket files are auto-discovered (no additional configuration required). -### Customize layout - -You can customize the WebSocket endpoint display with `title` and `slug` properties, similar to REST endpoints. For more details, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). - - ```yaml title="docs.yml" {9-10} - navigation: - - api: API Reference - layout: - - user: - - endpoint: user.create - title: Create a User - slug: user-creation - - user.delete - - endpoint: WSS /v1/realtime - title: Realtime - ``` +## Customize the layout + +Use the `layout` property in `docs.yml` to control how WebSocket endpoints appear in the sidebar. Reference individual WebSocket endpoints with the `endpoint` keyword using the format `WSS /path`. + +You can also set a custom `title`, `slug`, `hidden`, or `availability` on each endpoint: + +```yaml title="docs.yml" +navigation: + - api: API Reference + layout: + - endpoint: WSS /plants/live-updates + title: Live plant updates + slug: live-updates + - endpoint: WSS /plants/growth-monitor + availability: beta +``` + +### Group endpoints into sections + +Organize WebSocket endpoints alongside REST endpoints under custom sections: + +```yaml title="docs.yml" +navigation: + - api: API Reference + layout: + - section: Plants + contents: + - GET /plants + - WSS /plants/live-updates + - WSS /plants/growth-monitor +``` + + +For shared layout options like renaming sections, adding pages and links, availability, and more, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). +