From cf36d03cd92774e33e8eeeb1f96eb573094ef5e7 Mon Sep 17 00:00:00 2001 From: Minae Lee Date: Wed, 28 Feb 2024 22:57:20 -0700 Subject: [PATCH] docs: update availability documentation (#3078) * docs: document x-fern-availability openapi extension * docs: add details about how to use availability component * docs: wording update * docs: update desc of generally-available availability property behavior --- .../content/components/availability.mdx | 16 +++++---- .../define-your-api/ferndef/availability.mdx | 12 +++---- .../define-your-api/openapi/extensions.mdx | 33 ++++++++++++++++--- 3 files changed, 43 insertions(+), 18 deletions(-) diff --git a/fern/docs/pages/fern-docs/content/components/availability.mdx b/fern/docs/pages/fern-docs/content/components/availability.mdx index 947536e4aeb..6b3c8b04495 100644 --- a/fern/docs/pages/fern-docs/content/components/availability.mdx +++ b/fern/docs/pages/fern-docs/content/components/availability.mdx @@ -1,17 +1,21 @@ --- title: Fern | Indicate the Availability of an endpoint -description: Indicate the status of an endpoint using the Availability component. Display whether the endpoint is in beta, generally available, or deprecated. +description: Indicate the status of a feature using the Availability component. Display a tag of beta, generally available, or deprecated. --- -The `Availability` component is used to indicate the availability status of an endpoint. +The `Availability` component is used to indicate the availability status of a feature, such as an endpoint. This component renders as a tag within your documentation. -Availability Prop: +Within the API reference documentation generated using Fern Docs, use the [Fern Definition `availability`](/overview/define-your-api/ferndef/availability) property or the [OpenAPI extension `x-fern-availability`](/overview/define-your-api/openapi/extensions) to indicate availability. + +In the Markdown/MDX pages that make up the rest of your documentation site, use the `Availability` component as shown below to render the tag. + +Availability prop: **type**: 'beta' | 'GA' | 'deprecated' ## Beta availability -Indicates that an endpoint is in . This means that the endpoint is still in development and may change before it is released to the public. +Indicates that a feature is in . This means that the feature is still in development and may change before it is released to the public. ```mdx @@ -19,7 +23,7 @@ Indicates that an endpoint is in . This means that t ## General availability -Indicates that an endpoint is . This means that the endpoint is ready for use in production. +Indicates that a feature is . This means that the feature is ready for use in production. ```mdx @@ -27,7 +31,7 @@ Indicates that an endpoint is . This means that the en ## Deprecated availability -Indicates that an endpoint is . This means that the endpoint is no longer supported and will be removed in a future release. +Indicates that a feature is . This means that the feature is no longer supported and will be removed in a future release. ```mdx diff --git a/fern/docs/pages/overview/define-your-api/ferndef/availability.mdx b/fern/docs/pages/overview/define-your-api/ferndef/availability.mdx index ee93422dc16..7ee605329ac 100644 --- a/fern/docs/pages/overview/define-your-api/ferndef/availability.mdx +++ b/fern/docs/pages/overview/define-your-api/ferndef/availability.mdx @@ -1,12 +1,10 @@ You can add `availability` to an endpoint, type, or property within your Fern Definition. Availability can be: -- `in-development` which means it is being worked on; will show a `beta` tag -- `pre-release` which means it is available; will show a `beta` tag -- `deprecated` which means it will be removed in the future; will show a `deprecated` tag -- `generally-available` which means it is stable and available for use; will not show a tag - -By default, all endpoints, types, and properties are `generally-available`. +- `in-development` which means it is being worked on; will show a `Beta` tag +- `pre-release` which means it is available; will show a `Beta` tag +- `deprecated` which means it will be removed in the future; will show a `Deprecated` tag +- `generally-available` which means it is stable and available for use; will show a `GA` tag ## Endpoint @@ -91,4 +89,4 @@ In Fern Docs, this will look like: In Fern Docs, this will look like: -![property deprecated](https://fern-image-hosting.s3.amazonaws.com/property-deprecated.png) \ No newline at end of file +![property deprecated](https://fern-image-hosting.s3.amazonaws.com/property-deprecated.png) diff --git a/fern/docs/pages/overview/define-your-api/openapi/extensions.mdx b/fern/docs/pages/overview/define-your-api/openapi/extensions.mdx index b1348260ee4..a964d1790c0 100644 --- a/fern/docs/pages/overview/define-your-api/openapi/extensions.mdx +++ b/fern/docs/pages/overview/define-your-api/openapi/extensions.mdx @@ -266,7 +266,7 @@ export interface Person { # <---- Overridden name } ``` -## Parameter Names +## Parameter names The `x-fern-parameter-name` extension allows you to customize the variable name of OpenAPI parameters. @@ -458,7 +458,7 @@ and sent as `false` for the non-streaming variant. Additionally, a stream of the is returned in the streaming variant, whereas the `Logs` array is returned in the non-streaming variant. -## Ignoring Schemas or endpoints +## Ignoring schemas or endpoints If you want Fern to skip reading any endpoint or schemas, you can use the `x-fern-ignore` extension. @@ -543,7 +543,7 @@ shown in the third tab. -## Request + Response Examples +## Request + response examples While OpenAPI has several fields for examples, there is no easy way to associate a request with a response. This is expecially useful when @@ -580,7 +580,7 @@ components: type: integer ``` -### Code Samples +### Code samples If you'd like to specify custom code samples for your example, use `code-samples`. @@ -605,6 +605,29 @@ paths: ``` If you're on the Fern Starter plan for SDKs you won't -have to worry about manually adding code samples! Our generators will do that for you. +have to worry about manually adding code samples! Our generators will do that for you. + +### Availability + +The `x-fern-availability` extension is used to mark the availability of an endpoint. The availability information propagates into the generated Fern Docs website as visual tags. + +The options are: +- `beta` +- `generally-available` +- `deprecated` + +The example below marks that the `POST /pet` endpoint is `deprecated`. + + +```yaml +paths: + /pet: + post: + x-fern-availability: deprecated <---- + ... +``` + + +### Request new extensions If there's an extension you want that doesn't already exist, file an [issue](https://github.com/fern-api/fern/issues/new) to start a discussion about it.