diff --git a/docs/cli.md b/docs/cli.md
index b4d762f1..551dabab 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -185,7 +185,7 @@ Discovery semantics:
 | `--description` | - | any string | library default | OpenAPI `info.description` (Markdown / CommonMark supported) |
 | `--output` | `-o` | file path | stdout | Write generated content to file |
 | `--format` | `-f` | `json`, `yaml` | `json` | Output serialization format |
-| `--openapi-version` | - | `3.0`, `3.1`, `3.2` | `3.1` | OpenAPI schema version |
+| `--openapi-version` | - | `3.0`, `3.1`, `3.2` | `3.1` | OpenAPI schema version. See [version selection guidance](faq.md#openapi-30-vs-31-vs-32-which-one-should-i-use). |
 | `--pretty` | `-p` | flag | `false` | Pretty-print JSON output (adds indentation); no effect on YAML |
 | `--route-prefix` | - | any string (or `""`) | `/api` | HTTP route prefix from `host.json` `extensions.http.routePrefix`. See [Route Prefix](route-prefix.md). |
 | `--fail-on-empty-paths` | - | flag | `false` | Exit with code 1 if the generated spec has no paths |
diff --git a/docs/configuration.md b/docs/configuration.md
index 2a5acdff..fa66e013 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -207,6 +207,9 @@ Supported versions:
 - `OPENAPI_VERSION_3_1` (`"3.1.0"`)
 - `OPENAPI_VERSION_3_2` (`"3.2.0"`)
 
+For guidance on choosing a version for downstream consumers such as Azure API
+Management, see the [OpenAPI version FAQ](faq.md#openapi-30-vs-31-vs-32-which-one-should-i-use).
+
 ```python
 from azure_functions_openapi import OPENAPI_VERSION_3_1, get_openapi_json
 
diff --git a/docs/faq.md b/docs/faq.md
index 94909fcb..1c339aba 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -2,7 +2,11 @@
 
 ## OpenAPI 3.0 vs 3.1 vs 3.2: which one should I use?
 
-Use 3.0.0 if downstream tooling in your stack still expects OpenAPI 3.0.
+Use 3.0.0 if downstream tooling in your stack still expects OpenAPI 3.0. For
+example, Azure API Management supports OpenAPI 2.0 and 3.0.x, while it
+treats OpenAPI 3.1 as import only (3.1-specific constructs are ignored or
+downgraded) and recommends 2.0 or 3.0.x for full fidelity. See
+[API formats support in Azure API Management](https://learn.microsoft.com/en-us/azure/api-management/api-management-api-import-restrictions).
 
 Use 3.1.0 if your tooling supports it and you want newer JSON Schema alignment.