From 4c2d4be0f74ae16454d2418e4c6e4335886397f1 Mon Sep 17 00:00:00 2001 From: Yeongseon Choe Date: Fri, 30 Oct 2026 19:34:59 +0900 Subject: [PATCH 1/2] docs(faq): name Azure API Management in the OpenAPI version guidance The 3.0 versus 3.1 entry named no downstream consumer. Add Azure API Management, which supports OpenAPI 2.0 and 3.0.x and accepts 3.1 for import only, and link to Microsoft import restrictions instead of restating them. Refs #861 Co-authored-by: sisyphus-dev-ai --- docs/faq.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) 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. From aaef342fdf2a3ea61925406fa135ffd10c701346 Mon Sep 17 00:00:00 2001 From: Yeongseon Choe Date: Fri, 30 Oct 2026 19:34:59 +0900 Subject: [PATCH 2/2] docs: link the OpenAPI version option and section to the FAQ guidance The places where readers choose a version, the --openapi-version option and the OpenAPI version selection section, did not point to the FAQ entry that explains the choice. Refs #861 Co-authored-by: sisyphus-dev-ai --- docs/cli.md | 2 +- docs/configuration.md | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/cli.md b/docs/cli.md index 54b50134..dcba0828 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -161,7 +161,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 0c3cb6ac..bcb034d7 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