diff --git a/docs/reference/plugins/openapi.mdx b/docs/reference/plugins/openapi.mdx index a16816e4..01b1a390 100644 --- a/docs/reference/plugins/openapi.mdx +++ b/docs/reference/plugins/openapi.mdx @@ -27,6 +27,7 @@ npm install --save-dev @zenstackhq/openapi | summary | String | API summary | No | | | securitySchemes | Object | Security schemes for the API. See [here](#security-schemes) for more details. | No | | | 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 | | #### API flavor @@ -64,6 +65,22 @@ The names of the configured security schemes will be added to the root `security You can override the security scheme for a specific model or operation by using the `@@openapi.meta` attribute. +#### Model name mapping + +The `modelNameMapping` option is an object that maps ZModel model names to OpenAPI resource names. This is useful for example when you want to use plural names in URL endpoints. It's only effective for the `rest` flavor. The mapping can be partial. You only need to specify the model names that you want to override. + +```zmodel +plugin openapi { + provider = '@zenstackhq/openapi' + prefix = '/api' + modelNameMapping = { + User: 'users' + } +} +``` + +With the above configuration, the `User` operations will be generated under `/api/users` instead of `/api/user`. + ### Attributes - `@@openapi.meta` diff --git a/docs/reference/server-adapters/api-handlers/rest.mdx b/docs/reference/server-adapters/api-handlers/rest.mdx index 69bfa814..67365c6f 100644 --- a/docs/reference/server-adapters/api-handlers/rest.mdx +++ b/docs/reference/server-adapters/api-handlers/rest.mdx @@ -84,6 +84,22 @@ The factory function accepts an options object with the following fields: Optional. A `number` field representing the default page size for listing resources and relationships. Defaults to 100. Set to Infinity to disable pagination. +- modelNameMapping + + Optional. An `Record` value that provides a mapping from model names (as defined in ZModel) to URL path names. This is useful for example when you want to use plural names in URL endpoints: + + ```ts + // endpoint for accessing User model will then be ".../users" + RestApiHandler({ + modelNameMapping: { + User: 'users' + } + }) + ``` + + The mapping can be partial. You only need to specify the model names that you want to override. If a mapping is provided, only the mapped url path is valid, and accessing to unmapped path will be denied. + + ## Endpoints and Features The RESTful API handler conforms to the the [JSON:API](https://jsonapi.org/format/) v1.1 specification for its URL design and input/output format. The following sections list the endpoints and features are implemented. The examples refer to the following schema modeling a blogging app: diff --git a/docs/reference/zmodel-language.md b/docs/reference/zmodel-language.md index 34ef8b85..ebba39ff 100644 --- a/docs/reference/zmodel-language.md +++ b/docs/reference/zmodel-language.md @@ -757,7 +757,7 @@ model User { } ``` -wil be translated to the following Prisma schema: +will be translated to the following Prisma schema: ```zmodel model User { @@ -766,6 +766,21 @@ model User { } ``` +##### @meta + +```zmodel +attribute @meta(_ name: String, _ value: Any) +``` + +Adds arbitrary metadata to a field. The metadata can be accessed by custom plugins for code generation, or at runtime from the `modelMeta` object exported from `@zenstackhq/runtime/model-meta`. The `value` parameter can be an arbitrary literal expression, including object literals. + +```zmodel +model User { + id Int @id + name String @meta(name: "description", value: "The name of the user") +} +``` + #### Model attributes ##### @@id @@ -927,7 +942,7 @@ model User { } ``` -wil be translated to the following Prisma schema: +will be translated to the following Prisma schema: ```zmodel model User { @@ -937,6 +952,21 @@ model User { } ``` +##### @@meta + +```zmodel +attribute @meta(_ name: String, _ value: Any) +``` + +Adds arbitrary metadata to a field. The metadata can be accessed by custom plugins for code generation, or at runtime from the `modelMeta` object exported from `@zenstackhq/runtime/model-meta`. The `value` parameter can be an arbitrary literal expression, including object literals. + +```zmodel +model User { + id Int @id + @@meta('description', 'This is a user model') +} +``` + ### Predefined attribute functions ##### uuid() diff --git a/docs/the-complete-guide/part1/5-data-validation.md b/docs/the-complete-guide/part1/5-data-validation.md index e04c22e3..e4ace726 100644 --- a/docs/the-complete-guide/part1/5-data-validation.md +++ b/docs/the-complete-guide/part1/5-data-validation.md @@ -81,8 +81,8 @@ We can use data validation to improve our app's robustness in many places. Two s ```zmodel model Space { - ... - slug String @unique @regex('^[0-9a-zA-Z]{4,16}$') + ... + slug String @unique @regex('^[0-9a-zA-Z]{4,16}$') } ``` diff --git a/versioned_docs/version-1.x/the-complete-guide/part1/5-data-validation.md b/versioned_docs/version-1.x/the-complete-guide/part1/5-data-validation.md index 859aab07..09043e7b 100644 --- a/versioned_docs/version-1.x/the-complete-guide/part1/5-data-validation.md +++ b/versioned_docs/version-1.x/the-complete-guide/part1/5-data-validation.md @@ -80,8 +80,8 @@ We can use data validation to improve our app's robustness in many places. Two s ```zmodel model Space { - ... - slug String @unique @regex('^[0-9a-zA-Z]{4,16}$') + ... + slug String @unique @regex('^[0-9a-zA-Z]{4,16}$') } ```