From 6bd9d9a2c17d4e30c9e96ad354b691fbbd8fba5f Mon Sep 17 00:00:00 2001 From: Deep Singhvi Date: Thu, 22 Aug 2024 09:29:58 -0400 Subject: [PATCH] fix(docs): move audiences docs into own page (#4389) --- fern/docs.yml | 3 + .../openapi/extensions/audiences.mdx | 104 ++++++++++++++++++ .../openapi/extensions/others.mdx | 85 -------------- 3 files changed, 107 insertions(+), 85 deletions(-) create mode 100644 fern/pages/api-definition/openapi/extensions/audiences.mdx diff --git a/fern/docs.yml b/fern/docs.yml index 2323d141665..dd25068a13e 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -64,6 +64,9 @@ navigation: - page: Parameter Names path: ./pages/api-definition/openapi/extensions/parameter-names.mdx slug: parameter-names + - page: Audiences + path: ./pages/api-definition/openapi/extensions/audiences.mdx + slug: audiences - page: Other path: ./pages/api-definition/openapi/extensions/others.mdx slug: others diff --git a/fern/pages/api-definition/openapi/extensions/audiences.mdx b/fern/pages/api-definition/openapi/extensions/audiences.mdx new file mode 100644 index 00000000000..574669e8b9a --- /dev/null +++ b/fern/pages/api-definition/openapi/extensions/audiences.mdx @@ -0,0 +1,104 @@ +--- +title: Audiences +subtitle: Use `x-fern-audiences` to filter to relevant endpoints, schemas and properties +--- + +Audiences are a useful tool for segmenting your API for different consumers. Common examples of audiences include `public` +and `beta`. + + + Remember to filter your SDKs and Docs after specifying audiences. If **no audiences** are specified, + nothing will be filtered. + + + + +The following example configures the SDK to filter to the `public` audience: + +```yaml title="generators.yml" {3-4} +groups: + sdks: + audiences: + - public + generators: + - name: fernapi/fern-tyepscript-node-sdk + version: 0.8.8 +``` + + + +The following example configures the docs to filter to the `public` audience: + +```yaml title="docs.yml" {3-4} +navigation: + - api: API Reference + audiences: + - public +``` + + + + + + +## Audiences for Endpoints + +To mark an endpoint with a particular audience, add the `x-fern-audiences` extension to the relevant endpoint. + +In the example below, the `POST /users/sendEmail` endpoint is only available to public consumers: + +```yaml title="openapi.yml" {4-5} +paths: + /users/sendEmail: + post: + x-fern-audiences: + - public + operationId: send_email +``` + +## Audiences for Schemas + +Schemas can be marked for different audiences, as well. + +In this example, the `Email` type is available to both public and beta customers. + +```yaml title="openapi.yml" {13-15} +components: + schemas: + Email: + title: Email + type: object + properties: + subject: + type: string + body: + type: string + to: + type: string + x-fern-audiences: + - public + - beta +``` + +## Audiences for Properties + +Properties can be marked for different audiences, as well. + +In this example, the `to` property is available to beta customers only. + +```yaml title="openapi.yml" {13-17} +components: + schemas: + Email: + title: Email + type: object + properties: + subject: + type: string + body: + type: string + to: + type: string + x-fern-audiences: + - beta +``` diff --git a/fern/pages/api-definition/openapi/extensions/others.mdx b/fern/pages/api-definition/openapi/extensions/others.mdx index dd8a76781f1..64d445b24ef 100644 --- a/fern/pages/api-definition/openapi/extensions/others.mdx +++ b/fern/pages/api-definition/openapi/extensions/others.mdx @@ -310,91 +310,6 @@ paths: /users: ... ``` -## Audiences - -Audiences are a useful tool for segmenting your API for different consumers. You can configure your Fern Docs to publish documentation specific to an `Audience`. You can use [audiences in your Fern Definition](/learn/api-definition/fern/audiences), too. - -Common examples of audiences include: - -- Internal consumers (e.g., frontend developers who use the API) -- Beta testers -- Customers - -By default, if no audience is specified, it will be accessible to all consumers. - -### Audiences for Endpoints - -To mark an endpoint with a particular audience, add the `x-fern-audiences` extension to the relevant endpoint. - -In the example below, the `POST /users/sendEmail` endpoint is only available to internal consumers: - -```yaml title="openapi.yml" {4-5} -paths: - /users/sendEmail: - post: - x-fern-audiences: - - internal - operationId: send_email - ... -``` - -### Audiences for Components - -Components can be marked for different audiences, as well. - -In this example, the `Email` type is available to both internal and beta customers, while the `to` property is available to beta customers only: - -```yaml title="openapi.yml" {13-17} -components: - schemas: - Email: - title: Email - type: object - properties: - subject: - type: string - body: - type: string - to: - type: string - x-fern-audiences: <-- property audience - - beta - x-fern-audiences: <-- type audience - - internal - - beta -``` - -### Audiences for SDKs - -In `generators.yml`, you can apply audience filters so that only certain -endpoints are passed to the generators. - -The following example configures the SDKs to filter for the `customers` audience: - -```yaml title="generators.yml" {3-4} -groups: - sdks: - audiences: - - customers - generators: - - name: fernapi/fern-tyepscript-node-sdk - version: 0.8.8 - ... -``` - -### Audiences for Docs - -If generating Fern Docs, update your `docs.yml` configuration to include your audiences. - -The following example shows how to configure your `docs.yml` to publish documentation for the `customers` audience: - -```yaml title="docs.yml" {3-4} -navigation: - - api: API Reference - audiences: - - customers -``` - ## Streaming The `x-fern-streaming` extension is used to specify that an endpoint's response is streamed.