zod openapi下載 - zod openapi源碼下載

zod-openapi

使用 Zod Schemas 建立 OpenAPI v3.x 文件的 Typescript 函式庫

安裝

透過npm 、 yarn或pnpm安裝：

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

用法

擴展佐德

這會改變 Zod 添加額外的.openapi()方法。在入口點的頂部調用它。您可以根據您的喜好透過兩種不同的方式來實現此目的。

子路徑導入

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

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

手動擴展

如果您有特定的 Zod 實例或您想要定位的另一個庫中的 Zod 實例，這非常有用。

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

extendZodWithOpenApi ( z ) ;

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

`.openapi()`

使用.openapi()方法將元資料新增至特定的 Zod 類型。 .openapi()方法採用具有下列選項的物件：

選項	描述
OpenAPI 選項	這將採用您在 SchemaObject 上放置的任何選項。
`effectType`	用於覆蓋 Zod 效果的建立類型
`header`	用於提供響應標頭的元數據
`param`	用於提供請求參數的元數據
`ref`	使用它來自動將模式註冊為可重複使用元件
`refType`	使用此選項可以設定文件中未引用的元件的建立類型。
`type`	使用它來覆蓋生成的類型。如果提供此選項，則不會產生元資料。
`unionOneOf`	設定為`true`以強制單一 ZodUnion 輸出`oneOf`而不是`anyOf` 。請參閱 CreateDocumentOptions 以了解全域選項

`createDocument`

建立 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 } ) } ,
            } ,
          } ,
        } ,
      } ,
    } ,
  } ,
} ) ;

建立以下物件：

{
  "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 "
      }
    }
  }
}

建立文件選項

createDocument採用可選的CreateDocumentOptions參數，可用於修改文件的建立方式。

 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`

建立 OpenAPI 架構物件以及任何已註冊的元件。 OpenAPI 3.1.0 架構物件與 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 ) ;

建立以下物件：

{
  "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 "
    }
  }
}

建立模式選項

createSchema採用可選的CreateSchemaOptions參數，該參數也可以採用與 CreateDocumentOptions 相同的選項以及以下選項：

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

請求參數

可以使用method鍵下的requestParams鍵建立查詢、路徑、標頭和 Cookie 參數，如下所示：

 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 ( ) } ) ,
        } ,
      } ,
    } ,
  } ,
} ) ;

如果您想以更傳統的方式聲明參數，您也可以使用參數鍵聲明它們。然後所有定義將被合併。

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

請求正文

在通常會聲明媒體類型的地方，將schema設定為 Zod 架構，如下所示。

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

如果您希望對架構使用 OpenAPI 語法，只需將 OpenAPI 架構新增至schema欄位即可。

回應

與請求正文類似，只需將schema設定為您的 Zod 架構，如下所示。您可以使用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 ( ) ,
            } ) ,
          } ,
        } ,
      } ,
    } ,
  } ,
} ) ;

回調

 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 ( ) } ) ,
                      } ,
                    } ,
                  } ,
                } ,
              } ,
            } ,
          } ,
        } ,
      } ,
    } ,
  } ,
} ) ;

建立組件

OpenAPI 允許您定義可重複使用的元件，而該程式庫允許您以兩種不同的方式複製該元件。

自動註冊模式
手動註冊架構

模式

如果我們以createDocument中的範例為例並建立title ，如下所示

自動註冊架構

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

無論在文件中的架構中使用title ，它都會被建立為引用。

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

然後title將作為文檔組件部分中的模式輸出。

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

這可能是創建重複性較低的開放 API 文件的極其強大的方法。有一些開放 API 功能，例如鑑別器映射，要求聯合中的所有模式都包含參考。

手動註冊架構

註冊架構而不是添加ref的另一種方法是將其直接添加到元件中。這仍然會以與ref相同的方式運作。因此，每當我們遇到該 Zod 類型時，我們都會將其替換為引用。

例如。

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

不幸的是，作為該庫的限制，您需要將.openapi()欄位或.describe()附加到您傳遞到元件中的架構，否則您可能無法獲得元件產生的全部功能。因此，我建議使用自動註冊組件而不是手動註冊。

參數

查詢、路徑、標頭和 Cookie 參數可以類似地註冊：

 // 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 ,
    } ,
  } ,
} ) ;

回應頭

回應頭可以類似地註冊：

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

回應

也可以註冊整個回复

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

回調

回呼也可以註冊

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