@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.

Installation

npm install --save-dev @zenstackhq/openapi

Options

Name	Type	Description	Required	Default
output	String	Output file path (with suffix .yaml or .json, relative to the path of ZModel)	Yes
flavor	String	API flavor: "rpc" or "rest". See here for more details.	No	rpc
specVersion	String	OpenAPI specification version	No	3.1.0
title	String	API title	No	ZenStack Generated API
version	String	API version	No	1.0.0
prefix	String	API path prefix, e.g., '/api'	No
description	String	API description	No
summary	String	API summary	No
securitySchemes	Object	Security schemes for the API. See here 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

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.

• rpc

  Fully mirrors PrismaClient's query API.

• rest

  RESTful resource-centric endpoints using JSON:API as transportation format

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:

  Name	Type	Description	Default
  security	Array	Security for this model
  tagDescription	String	Description 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:

  Name	Type	Description	Default
  security	Array	Security for this operation
  description	String	Description of the operation
  method	String	HTTP method of the operation	Depends on the operation
  path	String	API endpoint path of the operation	The corresponding Prisma operation name
  summary	String	Summary of the operation
  tags	Array	Tags of the operation
  deprecated	Bool	Whether the operation is deprecated	false

  Sample usage

Using "rpc" flavor

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
        }
    })
}

Using "rest" flavor

model User {
    id String @id
    email String @unique

    @@openapi.meta({
        security: [ { basic: [] } ],
        tagDescription: 'Operations for managing users',
    })
}

• @@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'
}