From a29a59b192d3f57217bafd0265101e75365f6214 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 25 Aug 2025 08:33:59 -0400 Subject: [PATCH] add generators.yml reference page to OpenAPI section --- fern/products/api-def/api-def.yml | 2 + .../reference/generators-reference.mdx | 8 ++ .../reference/generators-yml-reference.mdx | 104 +---------------- fern/snippets/openapi-specs.mdx | 108 ++++++++++++++++++ 4 files changed, 120 insertions(+), 102 deletions(-) create mode 100644 fern/products/api-def/openapi-pages/reference/generators-reference.mdx create mode 100644 fern/snippets/openapi-specs.mdx diff --git a/fern/products/api-def/api-def.yml b/fern/products/api-def/api-def.yml index d23442ea6..73d8bf5ea 100644 --- a/fern/products/api-def/api-def.yml +++ b/fern/products/api-def/api-def.yml @@ -72,6 +72,8 @@ navigation: - page: FastAPI path: ./openapi-pages/server-frameworks/fastapi.mdx slug: fastapi + - page: generators.yml reference + path: ./openapi-pages/reference/generators-reference.mdx - section: AsyncAPI collapsed: true slug: asyncapi diff --git a/fern/products/api-def/openapi-pages/reference/generators-reference.mdx b/fern/products/api-def/openapi-pages/reference/generators-reference.mdx new file mode 100644 index 000000000..00dec2c86 --- /dev/null +++ b/fern/products/api-def/openapi-pages/reference/generators-reference.mdx @@ -0,0 +1,8 @@ +--- +title: OpenAPI generators.yml reference +description: Reference for configuring OpenAPI specifications in your generators.yml file +--- + +Configure how your OpenAPI specification is processed and transformed into SDKs using the `generators.yml` configuration file. + + \ No newline at end of file diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx index 49c108261..85fd1661a 100644 --- a/fern/products/sdks/reference/generators-yml-reference.mdx +++ b/fern/products/sdks/reference/generators-yml-reference.mdx @@ -171,109 +171,9 @@ api: ### Specification Types -#### OpenAPI +#### OpenAPI -```yaml -api: - specs: - - openapi: "./openapi.yml" - origin: "https://api.example.com/openapi.json" - overrides: "./openapi-overrides.yml" - namespace: "v1" - settings: - title-as-schema-name: true - inline-path-parameters: false - prefer-undiscriminated-unions-with-literals: true - filter: - endpoints: ["POST /users", "GET /users/{id}"] - example-generation: - request: - max-depth: 2 -``` - - - Path to the OpenAPI specification file. - - - - URL of the API definition origin for polling updates. - - - - Path to OpenAPI overrides file. - - - - Namespace for the specification. - - - - OpenAPI-specific generation settings. - - - - Whether to use the titles of schemas within an OpenAPI definition as the names of types within Fern. - - - - Whether to include path parameters within the generated in-lined request. - - - - Whether to prefer undiscriminated unions with literals. - - - - Whether to only include schemas referenced by endpoints in the generated SDK (tree-shaking). - - - - Preserves nullable schemas in API definition settings. When false, nullable schemas are treated as optional. - - - - Enables parsing deep object query parameters. - - - - Enables exploring readonly schemas in OpenAPI specifications. - - - - Enables respecting forward compatible enums in OpenAPI specifications. - - - - Enables using the `bytes` type for binary responses. Defaults to file stream. - - - - The default encoding of form parameters. Options: `form`, `json`. - - - - Configure what `additionalProperties` should default to when not explicitly defined on a schema. - - - - If true, convert strings with format date to strings. If false, convert to dates. - - - - If true, preserve oneOf structures with a single schema. If false, unwrap them. - - - - Endpoints to include in the generated SDK (e.g., "POST /users"). - - - - Controls the maximum depth for which optional properties will have examples generated. A depth of 0 means no optional properties will have examples. - - - - Controls the maximum depth for which optional properties will have examples generated in responses. - + #### AsyncAPI diff --git a/fern/snippets/openapi-specs.mdx b/fern/snippets/openapi-specs.mdx new file mode 100644 index 000000000..e488336e6 --- /dev/null +++ b/fern/snippets/openapi-specs.mdx @@ -0,0 +1,108 @@ +```yaml title="generators.yml" +api: + specs: + - openapi: "./openapi.yml" + origin: "https://api.example.com/openapi.json" + overrides: "./openapi-overrides.yml" + namespace: "v1" + settings: + title-as-schema-name: true + inline-path-parameters: false + inline-all-of-schemas: true + prefer-undiscriminated-unions-with-literals: true + filter: + endpoints: ["POST /users", "GET /users/{id}"] + example-generation: + request: + max-depth: 2 +``` + + + Path to the OpenAPI specification file. + + + + URL of the API definition origin for polling updates. + + + + Path to OpenAPI overrides file. + + + + Namespace for the specification. + + + + OpenAPI-specific generation settings. + + + + Whether to use the titles of schemas within an OpenAPI definition as the names of types within Fern. + + + + Whether to include path parameters within the generated in-lined request. + + + + Whether to inline `allOf` schemas during code generation. When true, Fern recursively visits `allOf` schema definitions and inlines them into the child schema. When false, `allOf` schemas are extended through inheritance. + + Enabling this setting allows child schemas to override parent property requirements. For example, a child schema can mark a parent's required property as optional. Without this setting, Fern ignores the child schema's optional declaration and preserves the parent schema's requirement instead. + + + + Whether to prefer undiscriminated unions with literals. + + + + Whether to only include schemas referenced by endpoints in the generated SDK (tree-shaking). + + + + Preserves nullable schemas in API definition settings. When false, nullable schemas are treated as optional. + + + + Enables parsing deep object query parameters. + + + + Enables exploring readonly schemas in OpenAPI specifications. + + + + Enables respecting forward compatible enums in OpenAPI specifications. + + + + Enables using the `bytes` type for binary responses. Defaults to file stream. + + + + The default encoding of form parameters. Options: `form`, `json`. + + + + Configure what `additionalProperties` should default to when not explicitly defined on a schema. + + + + If true, convert strings with format date to strings. If false, convert to dates. + + + + If true, preserve oneOf structures with a single schema. If false, unwrap them. + + + + Endpoints to include in the generated SDK (e.g., "POST /users"). + + + + Controls the maximum depth for which optional properties will have examples generated. A depth of 0 means no optional properties will have examples. + + + + Controls the maximum depth for which optional properties will have examples generated in responses. +