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/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. +