From d1138298230fe74c431c192ec262e93e2fdbc99e Mon Sep 17 00:00:00 2001 From: Lena Georgescu Date: Sat, 16 Aug 2025 16:34:00 +0200 Subject: [PATCH 1/2] docs: add description for new plugin option "includeOpenApiIgnored" --- docs/reference/plugins/openapi.mdx | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/reference/plugins/openapi.mdx b/docs/reference/plugins/openapi.mdx index 01b1a390..2e12d1eb 100644 --- a/docs/reference/plugins/openapi.mdx +++ b/docs/reference/plugins/openapi.mdx @@ -26,6 +26,7 @@ npm install --save-dev @zenstackhq/openapi | description | String | API description | No | | | summary | String | API summary | No | | | securitySchemes | Object | Security schemes for the API. See [here](#security-schemes) for more details. | No | | +| includeOpenApiIgnored | Boolean | If true, models tagged with `@openapi.ignore` are included in the generated spec. | No | false | | omitInputDetails | Boolean | **Only valid for "rpc" flavor.** If true, the output spec will not contain detailed structures for query/mutation input fields like `where`, `select`, `data`, etc. These fields will be typed as generic objects. Use this option to reduce the size of the generated spec. | No | false | | modelNameMapping | Object | **Only effective for "rest" flavor.** See [here](#model-name-mapping) for more details. | No | | @@ -179,6 +180,23 @@ model User { Mark a data model to be ignored when generating OpenAPI specification. + By default, ignored models are excluded from the spec. If you set the plugin option `includeOpenApiIgnored = true`, they will be included. + This is useful when you want to generate two different specs, for example a public spec for customers and an internal spec for your team (which may include additional internal models). + + You can configure the plugin twice with different outputs: + + ```zmodel + plugin openapi { + provider = '@zenstackhq/openapi' + output = './openapi-public.yaml' + } + + plugin openapi { + provider = '@zenstackhq/openapi' + output = './openapi-internal.yaml' + includeOpenApiIgnored = true + } + ``` ### Example ```zmodel title='schema.zmodel' From abb6bb49b99b38123b2ba5c15588511f37719135 Mon Sep 17 00:00:00 2001 From: Lena Georgescu Date: Sat, 16 Aug 2025 16:51:57 +0200 Subject: [PATCH 2/2] fix: distinct plugin block names and spelling of attributes --- docs/reference/plugins/openapi.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reference/plugins/openapi.mdx b/docs/reference/plugins/openapi.mdx index 2e12d1eb..104a4511 100644 --- a/docs/reference/plugins/openapi.mdx +++ b/docs/reference/plugins/openapi.mdx @@ -26,7 +26,7 @@ npm install --save-dev @zenstackhq/openapi | description | String | API description | No | | | summary | String | API summary | No | | | securitySchemes | Object | Security schemes for the API. See [here](#security-schemes) for more details. | No | | -| includeOpenApiIgnored | Boolean | If true, models tagged with `@openapi.ignore` are included in the generated spec. | No | false | +| includeOpenApiIgnored | Boolean | If true, models tagged with `@@openapi.ignore` are included in the generated spec. | No | false | | omitInputDetails | Boolean | **Only valid for "rpc" flavor.** If true, the output spec will not contain detailed structures for query/mutation input fields like `where`, `select`, `data`, etc. These fields will be typed as generic objects. Use this option to reduce the size of the generated spec. | No | false | | modelNameMapping | Object | **Only effective for "rest" flavor.** See [here](#model-name-mapping) for more details. | No | | @@ -183,15 +183,15 @@ model User { By default, ignored models are excluded from the spec. If you set the plugin option `includeOpenApiIgnored = true`, they will be included. This is useful when you want to generate two different specs, for example a public spec for customers and an internal spec for your team (which may include additional internal models). - You can configure the plugin twice with different outputs: + You can configure the plugin twice with different outputs and distinct block names: ```zmodel - plugin openapi { + plugin openapiPublic { provider = '@zenstackhq/openapi' output = './openapi-public.yaml' } - plugin openapi { + plugin openapiInternal { provider = '@zenstackhq/openapi' output = './openapi-internal.yaml' includeOpenApiIgnored = true