Download zod openapi - download do código-fonte zod openapi

zod-openapi

Uma biblioteca Typescript para usar esquemas Zod para criar documentação OpenAPI v3.x

Instalar

Instale via npm , yarn ou pnpm :

npm install zod zod-openapi
# # or
yarn add zod zod-openapi
# # or
pnpm install zod zod-openapi

Uso

Estender Zod

Isso transforma Zod para adicionar um método .openapi() extra. Chame isso no topo do(s) seu(s) ponto(s) de entrada. Você pode conseguir isso de duas maneiras diferentes, dependendo da sua preferência.

Importação de subcaminho

 import 'zod-openapi/extend' ;
import { z } from 'zod' ;

z . string ( ) . openapi ( { description : 'hello world!' , example : 'hello world' } ) ;

Extensão Manual

Isso é útil se você tiver uma instância específica do Zod ou uma instância do Zod de outra biblioteca que gostaria de atingir.

 import { z } from 'zod' ;
import { extendZodWithOpenApi } from 'zod-openapi' ;

extendZodWithOpenApi ( z ) ;

z . string ( ) . openapi ( { description : 'hello world!' , example : 'hello world' } ) ;

`.openapi()`

Use o método .openapi() para adicionar metadados a um tipo Zod específico. O método .openapi() pega um objeto com as seguintes opções:

Opção	Descrição
Opções OpenAPI	Isso aceitará qualquer opção que você colocaria em um SchemaObject.
`effectType`	Use para substituir o tipo de criação de um Efeito Zod
`header`	Use para fornecer metadados para cabeçalhos de resposta
`param`	Use para fornecer metadados para parâmetros de solicitação
`ref`	Use isto para registrar automaticamente um esquema como um componente reutilizável
`refType`	Use isto para definir o tipo de criação de um componente que não é referenciado no documento.
`type`	Use isto para substituir o tipo gerado. Se isso for fornecido, nenhum metadado será gerado.
`unionOneOf`	Defina como `true` para forçar um único ZodUnion a gerar `oneOf` em vez de `anyOf` . Consulte CreateDocumentOptions para obter uma opção global

`createDocument`

Cria um objeto de documentação OpenAPI

 import 'zod-openapi/extend' ;
import { z } from 'zod' ;
import { createDocument } from 'zod-openapi' ;

const jobId = z . string ( ) . openapi ( {
  description : 'A unique identifier for a job' ,
  example : '12345' ,
  ref : 'jobId' ,
} ) ;

const title = z . string ( ) . openapi ( {
  description : 'Job title' ,
  example : 'My job' ,
} ) ;

const document = createDocument ( {
  openapi : '3.1.0' ,
  info : {
    title : 'My API' ,
    version : '1.0.0' ,
  } ,
  paths : {
    '/jobs/{jobId}' : {
      put : {
        requestParams : { path : z . object ( { jobId } ) } ,
        requestBody : {
          content : {
            'application/json' : { schema : z . object ( { title } ) } ,
          } ,
        } ,
        responses : {
          '200' : {
            description : '200 OK' ,
            content : {
              'application/json' : { schema : z . object ( { jobId , title } ) } ,
            } ,
          } ,
        } ,
      } ,
    } ,
  } ,
} ) ;

Cria o seguinte objeto:

{
  "openapi" : " 3.1.0 " ,
  "info" : {
    "title" : " My API " ,
    "version" : " 1.0.0 "
  },
  "paths" : {
    "/jobs/{jobId}" : {
      "put" : {
        "parameters" : [
          {
            "in" : " path " ,
            "name" : " jobId " ,
            "description" : " A unique identifier for a job " ,
            "schema" : {
              "$ref" : " #/components/schemas/jobId "
            }
          }
        ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "type" : " object " ,
                "properties" : {
                  "title" : {
                    "type" : " string " ,
                    "description" : " Job title " ,
                    "example" : " My job "
                  }
                },
                "required" : [ " title " ]
              }
            }
          }
        },
        "responses" : {
          "200" : {
            "description" : " 200 OK " ,
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : " object " ,
                  "properties" : {
                    "jobId" : {
                      "$ref" : " #/components/schemas/jobId "
                    },
                    "title" : {
                      "type" : " string " ,
                      "description" : " Job title " ,
                      "example" : " My job "
                    }
                  },
                  "required" : [ " jobId " , " title " ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components" : {
    "schemas" : {
      "jobId" : {
        "type" : " string " ,
        "description" : " A unique identifier for a job " ,
        "example" : " 12345 "
      }
    }
  }
}

CriarOpções de Documento

createDocument usa um argumento CreateDocumentOptions opcional que pode ser usado para modificar como o documento é criado.

 const document = createDocument ( details , {
  defaultDateSchema : { type : 'string' , format : 'date-time' } , // defaults to { type: 'string' }
  unionOneOf : true , // defaults to false. Forces all ZodUnions to output oneOf instead of anyOf. An `.openapi()` `unionOneOf` value takes precedence over this one.
} ) ;

`createSchema`

Cria um objeto de esquema OpenAPI junto com quaisquer componentes registrados. Os objetos de esquema OpenAPI 3.1.0 são totalmente compatíveis com o esquema JSON.

 import 'zod-openapi/extend' ;
import { z } from 'zod' ;
import { createSchema } from 'zod-openapi' ;

const jobId = z . string ( ) . openapi ( {
  description : 'A unique identifier for a job' ,
  example : '12345' ,
  ref : 'jobId' ,
} ) ;

const title = z . string ( ) . openapi ( {
  description : 'Job title' ,
  example : 'My job' ,
} ) ;

const job = z . object ( {
  jobId ,
  title ,
} ) ;

const { schema , components } = createSchema ( job ) ;

Cria o seguinte objeto:

{
  "schema" : {
    "type" : " object " ,
    "properties" : {
      "jobId" : {
        "$ref" : " #/components/schemas/jobId "
      },
      "title" : {
        "type" : " string " ,
        "description" : " Job title " ,
        "example" : " My job "
      }
    },
    "required" : [ " jobId " , " title " ]
  },
  "components" : {
    "jobId" : {
      "type" : " string " ,
      "description" : " A unique identifier for a job " ,
      "example" : " 12345 "
    }
  }
}

CriarSchemaOptions

createSchema usa um parâmetro CreateSchemaOptions opcional que também pode usar as mesmas opções que CreateDocumentOptions junto com as seguintes opções:

 const { schema , components } = createSchema ( job , {
  schemaType : 'input' ; // This controls whether this should be rendered as a request (`input`) or response (`output`). Defaults to `output`
  openapi: '3.0.0' ; // OpenAPI version to use, defaults to `'3.1.0'`
  components: { jobId : z . string ( ) } // Additional components to use and create while rendering the schema
  componentRefPath: '#/definitions/' // Defaults to #/components/schemas/
} )

Parâmetros de solicitação

Os parâmetros de consulta, caminho, cabeçalho e cookie podem ser criados usando a chave requestParams na chave method da seguinte forma:

 createDocument ( {
  paths : {
    '/jobs/{a}' : {
      put : {
        requestParams : {
          path : z . object ( { a : z . string ( ) } ) ,
          query : z . object ( { b : z . string ( ) } ) ,
          cookie : z . object ( { cookie : z . string ( ) } ) ,
          header : z . object ( { 'custom-header' : z . string ( ) } ) ,
        } ,
      } ,
    } ,
  } ,
} ) ;

Se desejar declarar parâmetros de uma forma mais tradicional, você também pode declará-los usando a chave de parâmetros. As definições serão então todas combinadas.

 createDocument ( {
  paths : {
    '/jobs/{a}' : {
      put : {
        parameters : [
          z . string ( ) . openapi ( {
            param : {
              name : 'job-header' ,
              in : 'header' ,
            } ,
          } ) ,
        ] ,
      } ,
    } ,
  } ,
} ) ;

Corpo da Solicitação

Onde você normalmente declararia o tipo de mídia, defina o schema como seu esquema Zod da seguinte maneira.

 createDocument ( {
  paths : {
    '/jobs' : {
      get : {
        requestBody : {
          content : {
            'application/json' : { schema : z . object ( { a : z . string ( ) } ) } ,
          } ,
        } ,
      } ,
    } ,
  } ,
} ) ;

Se você deseja usar a sintaxe OpenAPI para seus esquemas, basta adicionar um esquema OpenAPI ao campo schema .

Respostas

Da mesma forma que o corpo da solicitação, basta definir o schema como seu esquema Zod da seguinte maneira. Você pode definir os cabeçalhos de resposta usando a chave headers .

 createDocument ( {
  paths : {
    '/jobs' : {
      get : {
        responses : {
          200 : {
            description : '200 OK' ,
            content : {
              'application/json' : { schema : z . object ( { a : z . string ( ) } ) } ,
            } ,
            headers : z . object ( {
              'header-key' : z . string ( ) ,
            } ) ,
          } ,
        } ,
      } ,
    } ,
  } ,
} ) ;

Retornos de chamada

 createDocument ( {
  paths : {
    '/jobs' : {
      get : {
        callbacks : {
          onData : {
            '{$request.query.callbackUrl}/data' : {
              post : {
                requestBody : {
                  content : {
                    'application/json' : { schema : z . object ( { a : z . string ( ) } ) } ,
                  } ,
                } ,
                responses : {
                  200 : {
                    description : '200 OK' ,
                    content : {
                      'application/json' : {
                        schema : z . object ( { a : z . string ( ) } ) ,
                      } ,
                    } ,
                  } ,
                } ,
              } ,
            } ,
          } ,
        } ,
      } ,
    } ,
  } ,
} ) ;

Criando Componentes

OpenAPI permite definir componentes reutilizáveis e esta biblioteca permite replicar isso de duas maneiras distintas.

Esquema de registro automático
Registrando esquema manualmente

Esquema

Se pegarmos o exemplo em createDocument e, em vez disso, criarmos title da seguinte maneira

Esquema de registro automático

 const title = z . string ( ) . openapi ( {
  description : 'Job title' ,
  example : 'My job' ,
  ref : 'jobTitle' , // <- new field
} ) ;

Sempre que title for usado em esquemas no documento, ele será criado como uma referência.

{ "$ref" : " #/components/schemas/jobTitle " }

title será então gerado como um esquema na seção de componentes da documentação.

{
  "components" : {
    "schemas" : {
      "jobTitle" : {
        "type" : " string " ,
        "description" : " Job title " ,
        "example" : " My job "
      }
    }
  }
}

Essa pode ser uma maneira extremamente poderosa de criar documentação Open API menos repetitiva. Existem alguns recursos da Open API, como mapeamento discriminador, que exigem que todos os esquemas na união contenham uma referência.

Esquema de registro manual

Outra maneira de registrar o esquema em vez de adicionar uma ref é adicioná-lo diretamente aos componentes. Isso ainda funcionará da mesma maneira que ref . Portanto, sempre que encontrarmos esse tipo Zod, iremos substituí-lo por uma referência.

por exemplo.

 createDocument ( {
  components : {
    schemas : {
      jobTitle : title , // this will register this Zod Schema as jobTitle unless `ref` in `.openapi()` is specified on the type
    } ,
  } ,
} ) ;

Infelizmente, como limitação desta biblioteca, você precisará anexar um campo .openapi() ou .describe() ao esquema que está passando para os componentes, caso contrário, poderá não obter todo o poder da geração do componente. Como resultado, recomendo utilizar os componentes de registro automático em vez do registro manual.

Parâmetros

Os parâmetros de consulta, caminho, cabeçalho e cookie podem ser registrados de forma semelhante:

 // Easy auto registration
const jobId = z . string ( ) . openapi ( {
  description : 'Job ID' ,
  example : '1234' ,
  param : { ref : 'jobRef' } ,
} ) ;

createDocument ( {
  paths : {
    '/jobs/{jobId}' : {
      put : {
        requestParams : {
          header : z . object ( {
            jobId ,
          } ) ,
        } ,
      } ,
    } ,
  } ,
} ) ;

// or more verbose auto registration
const jobId = z . string ( ) . openapi ( {
  description : 'Job ID' ,
  example : '1234' ,
  param : { in : 'header' , name : 'jobId' , ref : 'jobRef' } ,
} ) ;

createDocument ( {
  paths : {
    '/jobs/{jobId}' : {
      put : {
        parameters : [ jobId ] ,
      } ,
    } ,
  } ,
} ) ;

// or manual registeration
const otherJobId = z . string ( ) . openapi ( {
  description : 'Job ID' ,
  example : '1234' ,
  param : { in : 'header' , name : 'jobId' } ,
} ) ;

createDocument ( {
  components : {
    parameters : {
      jobRef : jobId ,
    } ,
  } ,
} ) ;

Cabeçalhos de resposta

Os cabeçalhos de resposta podem ser registrados de forma semelhante:

 const header = z . string ( ) . openapi ( {
  description : 'Job ID' ,
  example : '1234' ,
  header : { ref : 'some-header' } ,
} ) ;

// or

const jobIdHeader = z . string ( ) . openapi ( {
  description : 'Job ID' ,
  example : '1234' ,
} ) ;

createDocument ( {
  components : {
    headers : {
      someHeaderRef : jobIdHeader ,
    } ,
  } ,
} ) ;

Respostas

Respostas inteiras também podem ser registradas

 const response : ZodOpenApiResponseObject = {
  description : '200 OK' ,
  content : {
    'application/json' : {
      schema : z . object ( { a : z . string ( ) } ) ,
    } ,
  } ,
  ref : 'some-response' ,
} ;

//or

const response : ZodOpenApiResponseObject = {
  description : '200 OK' ,
  content : {
    'application/json' : {
      schema : z . object ( { a : z . string ( ) } ) ,
    } ,
  } ,
} ;

createDocument ( {
  components : {
    responses : {
      'some-response' : response ,
    } ,
  } ,
} ) ;

Retornos de chamada

Retornos de chamada também podem ser registrados

 const callback : ZodOpenApiCallbackObject = {
  ref : 'some-callback'
  post : {
    responses : {
      200 : {
        description : '200 OK' ,
        content : {
          'application/json' : {
            schema : z . object ( { a : z . string ( ) } ) ,
          }