Skip to main content

@zenstackhq/openapi

The @zenstackhq/openapi generates an OpenAPI V3 specification based on your ZModel schema. The output is a plain YAML or JSON file that can be used with tools like Swagger UI. You can also merge it with other OpenAPI specifications before serving it to your users.

Options

NameTypeDescriptionRequiredDefault
outputStringOutput file path (with suffix .yaml or .json, relative to the path of ZModel)Yes
flavorStringAPI flavor: "rpc" or "rest". See here for more details.Norpc
specVersionStringOpenAPI specification versionNo3.1.0
titleStringAPI titleNoZenStack Generated API
versionStringAPI versionNo1.0.0
prefixStringAPI path prefix, e.g., '/api'No
descriptionStringAPI descriptionNo
summaryStringAPI summaryNo
securitySchemesObjectSecurity schemes for the API. See here for more details.No

API flavor

The flavor option controls the style of API endpoints and data format of the generated specification. Currently we support two flavors: rpc and rest. The default flavor is rpc.

The two flavors correspond to the two style of APIs supported by ZenStack server adapters. See here for more details.

Security schemes

The securitySchemes option is an object containing security schemes for the API, following the specification here. The object will be generated as the securitySchemes field under the components section in the OpenAPI specification.

Example usage:

plugin openapi {
provider = '@zenstackhq/openapi'
securitySchemes = {
basic: { type: 'http', scheme: 'basic' },
bearer: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
apiKey: { type: 'apiKey', in: 'header', name: 'X-API-KEY' }
}
}

The names of the configured security schemes will be added to the root security field and inherited by all operations. The plugin also respects the access policy rules defined in the schema. If a operation is fully open (e.g., create operation with @@allow('create', true) rule), an empty security array will be added to the operation to mark it as unprotected.

You can override the security scheme for a specific model or operation by using the @@openapi.meta attribute.

Attributes

  • @@openapi.meta

        attribute @@openapi.meta(_ meta: Object)

    Provide metadata for a data model for generating OpenAPI specification. The input is an object containing customized configuration for each model and each CRUD operation. You can use it to override Http method, API endpoint path, description, summary, tags, security, and etc. Currently there's no type checking for the structure, but we'll add that in the near future.

    Model-level metadata

    The input object can contain the following top-level fields:

    NameTypeDescriptionDefault
    securityArraySecurity for this model
    tagDescriptionStringDescription of the tag generated for this model[Model Name] operations

    Operation-level metadata

    info

    Only supported by "rpc" flavor.

    The input object can contain operation-level metadata keyed by the Prisma operation name. Each entry can contain the following fields:

    NameTypeDescriptionDefault
    securityArraySecurity for this operation
    descriptionStringDescription of the operation
    methodStringHTTP method of the operationDepends on the operation
    pathStringAPI endpoint path of the operationThe corresponding Prisma operation name
    summaryStringSummary of the operation
    tagsArrayTags of the operation
    deprecatedBoolWhether the operation is deprecatedfalse

    Sample usage

model User {
id String @id
email String @unique

@@openapi.meta({
security: [ { basic: [] } ],
tagDescription: 'Operations for managing users',
findMany: {
description: 'Find users matching the given conditions'
},
delete: {
method: 'put',
path: 'dodelete',
description: 'Delete a unique user',
summary: 'Delete a user yeah yeah',
tags: ['delete', 'user'],
},
createMany: {
security: [],
deprecated: true
}
})
}
  • @@openapi.ignore

    attribute @@openapi.ignore()

    Mark a data model to be ignored when generating OpenAPI specification.

Example

schema.zmodel
datasource db {
provider = 'sqlite'
url = 'file:./dev.db'
}

plugin openapi {
provider = '@zenstackhq/openapi'
output = './openapi.yaml'
title = 'My awesome API'
version = '0.5.0'
summary = 'Created with ZenStack'
description = 'My awesome API created with ZenStack'
prefix = '/api'
}