(api definitions) Document group-environments-by-host option, small clarifying edits to api options (#1241)

Author: devalog

fern/products/sdks/reference/generators-yml-reference.mdx

@@ -202,7 +202,7 @@ api:
 </ParamField>
 
 <ParamField path="namespace" type="string" toc={true}>
-  Namespace for the specification.
+  Namespace for the specification. Useful for configuring a [single package with multiple API versions](/api-definitions/overview/project-structure#option-2-namespace-based-versioning).  
 </ParamField>
 
 <ParamField path="settings" type="object" toc={true}>
@@ -220,6 +220,10 @@ api:
 <ParamField path="settings.respect-nullable-schemas" type="boolean" default="false" toc={true}>
   Preserves nullable schemas in API definition settings. When false, nullable schemas are treated as optional.
 </ParamField>
+<ParamField path="settings.group-environments-by-host" type="boolean" default="false" toc={true}>
+  When enabled, groups servers by host into unified environments, enabling APIs with multiple protocols (REST, WebSocket, etc.) to share environment configuration. Environment URL IDs use the server name, with path or protocol suffixes added only when needed to resolve collisions.
+
+</ParamField>
 </Accordion>
 <Accordion title="gRPC/proto buffers">
 
@@ -264,7 +268,7 @@ api:
 </Accordion>
 <Accordion title="Conjure">
 
-```yaml
+```yaml title="generators.yml"
 api:
   specs:
     conjure: "./conjure-api.yml"

fern/snippets/openapi-specs.mdx

@@ -30,95 +30,95 @@ api:
 </ParamField>
 
 <ParamField path="namespace" type="string" toc={true}>
-  Namespace for the specification.
+  Namespace for the specification. Useful for configuring a [single package with multiple API versions](/api-definitions/overview/project-structure#option-2-namespace-based-versioning).
 </ParamField>
 
-<ParamField path="settings" type="OpenAPISettingsSchema" toc={true}>
+<ParamField path="settings" type="object" toc={true}>
   OpenAPI-specific generation settings.
 </ParamField>
 
 <ParamField path="settings.title-as-schema-name" type="boolean" default="true" toc={true}>
   Whether to use the titles of schemas within an OpenAPI definition as the names of types within Fern.
 </ParamField>
 
-<ParamField path="inline-path-parameters" type="boolean" default="false" toc={true}>
+<ParamField path="settings.inline-path-parameters" type="boolean" default="false" toc={true}>
   Whether to include path parameters within the generated in-lined request.
 </ParamField>
 
-<ParamField path="inline-all-of-schemas" type="boolean" default="false" toc={true}>
+<ParamField path="settings.inline-all-of-schemas" type="boolean" default="false" toc={true}>
   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.
 </ParamField>
 
-<ParamField path="prefer-undiscriminated-unions-with-literals" type="boolean" default="false" toc={true}>
+<ParamField path="settings.prefer-undiscriminated-unions-with-literals" type="boolean" default="false" toc={true}>
   Whether to prefer undiscriminated unions with literals.
 </ParamField>
 
-<ParamField path="only-include-referenced-schemas" type="boolean" default="false" toc={true}>
+<ParamField path="settings.only-include-referenced-schemas" type="boolean" default="false" toc={true}>
   Whether to only include schemas referenced by endpoints in the generated SDK (tree-shaking).
 </ParamField>
 
-<ParamField path="respect-nullable-schemas" type="boolean" default="false" toc={true}>
+<ParamField path="settings.respect-nullable-schemas" type="boolean" default="false" toc={true}>
   Preserves nullable schemas in API definition settings. When false, nullable schemas are treated as optional.
 </ParamField>
 
-<ParamField path="object-query-parameters" type="boolean" toc={true}>
+<ParamField path="settings.object-query-parameters" type="boolean" toc={true}>
   Enables parsing deep object query parameters.
 </ParamField>
 
-<ParamField path="respect-readonly-schemas" type="boolean" toc={true}>
+<ParamField path="settings.respect-readonly-schemas" type="boolean" toc={true}>
   Enables exploring readonly schemas in OpenAPI specifications.
 </ParamField>
 
-<ParamField path="respect-forward-compatible-enums" type="boolean" default="false" toc={true}>
+<ParamField path="settings.respect-forward-compatible-enums" type="boolean" default="false" toc={true}>
   Enables respecting forward compatible enums in OpenAPI specifications.
 </ParamField>
 
-<ParamField path="use-bytes-for-binary-response" type="boolean" toc={true}>
+<ParamField path="settings.use-bytes-for-binary-response" type="boolean" toc={true}>
   Enables using the `bytes` type for binary responses. Defaults to file stream.
 </ParamField>
 
-<ParamField path="default-form-parameter-encoding" type="FormParameterEncoding" default="json" toc={true}>
+<ParamField path="settings.default-form-parameter-encoding" type="string" default="json" toc={true}>
   The default encoding of form parameters. Options: `form`, `json`.
 </ParamField>
 
-<ParamField path="additional-properties-defaults-to" type="boolean" default="false" toc={true}>
+<ParamField path="settings.additional-properties-defaults-to" type="boolean" default="false" toc={true}>
   Configure what `additionalProperties` should default to when not explicitly defined on a schema.
 </ParamField>
 
-<ParamField path="type-dates-as-strings" type="boolean" default="true" toc={true}>
+<ParamField path="settings.type-dates-as-strings" type="boolean" default="true" toc={true}>
   If true, convert strings with format date to strings. If false, convert to dates.
 </ParamField>
 
-<ParamField path="preserve-single-schema-oneof" type="boolean" default="false" toc={true}>
+<ParamField path="settings.preserve-single-schema-oneof" type="boolean" default="false" toc={true}>
   If true, preserve oneOf structures with a single schema. If false, unwrap them.
 </ParamField>
 
-<ParamField path="filter.endpoints" type="list<string>" toc={true}>
+<ParamField path="settings.filter.endpoints" type="list of strings" toc={true}>
   Endpoints to include in the generated SDK (e.g., "POST /users").
 </ParamField>
 
-<ParamField path="example-generation.request.max-depth" type="integer" toc={true}>
+<ParamField path="settings.example-generation.request.max-depth" type="integer" toc={true}>
   Controls the maximum depth for which optional properties will have examples generated. A depth of 0 means no optional properties will have examples.
 </ParamField>
 
-<ParamField path="example-generation.response.max-depth" type="integer" toc={true}>
+<ParamField path="settings.example-generation.response.max-depth" type="integer" toc={true}>
   Controls the maximum depth for which optional properties will have examples generated in responses.
 </ParamField>
 
-<ParamField path="coerce-enums-to-literals" type="boolean" default="true" toc={true}>
+<ParamField path="settings.coerce-enums-to-literals" type="boolean" default="true" toc={true}>
   Controls whether enums are converted to literal types during code generation. When set to `false`, enums are preserved as enums rather than being converted to literal types. This is useful when you want to maintain the original enum structure from your OpenAPI specification.
 </ParamField>
 
-<ParamField path="idiomatic-request-names" type="boolean" default="false" toc={true}>
+<ParamField path="settings.idiomatic-request-names" type="boolean" default="false" toc={true}>
   Controls the naming convention for autogenerated request names. When enabled, places the verb before the noun in request names (e.g., `UsersListRequest` becomes `ListUsersRequest`), following more idiomatic naming patterns.
 
   Disabled by default to maintain backwards compatibility.
 
 </ParamField>
 
-<ParamField path="resolve-aliases" type="boolean" default="false" toc={true}>
+<ParamField path="settings.resolve-aliases" type="boolean" default="false" toc={true}>
   Inlines type aliases to simplify your generated SDK. When enabled, reduces
   unnecessary type definitions by replacing simple aliases with their underlying
   types directly. Useful for OpenAPI specs with many primitive or simple type
@@ -139,3 +139,7 @@ api:
         - OrganizationId
   ```
 </ParamField>
+<ParamField path="settings.group-environments-by-host" type="boolean" default="false" toc={true}>
+  When enabled, groups servers by host into unified environments, enabling APIs with multiple protocols (REST, WebSocket, etc.) to share environment configuration. Environment URL IDs use the server name, with path or protocol suffixes added only when needed to resolve collisions.
+
+</ParamField>