Kebijakan OASValidation

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Kebijakan OASValidation (Validasi Spesifikasi OpenAPI) memungkinkan Anda memvalidasi pesan permintaan atau respons masuk terhadap Spesifikasi OpenAPI 3.0, menggunakan format JSON atau YAML. Lihat Konten apa yang divalidasi?

Kebijakan OASValidation menentukan nama Spesifikasi OpenAPI yang akan digunakan untuk validasi saat langkah yang dilampiri kebijakan dieksekusi. Spesifikasi OpenAPI disimpan sebagai resource di lokasi standar berikut dalam paket proxy API: apiproxy/resources/oas. Dokumen Spesifikasi OpenAPI harus memiliki ekstensi .json, .yml, atau .yaml.

Tambahkan Spesifikasi OpenAPI sebagai resource ke paket proxy API menggunakan UI atau API, seperti yang dijelaskan dalam Mengelola resource.

Kebijakan ini adalah Kebijakan standar dan dapat di-deploy ke jenis lingkungan apa pun. Untuk mengetahui informasi tentang jenis dan ketersediaan kebijakan dengan setiap jenis lingkungan, lihat Jenis kebijakan.

Catatan: Anda hanya dapat menyimpan Spesifikasi OpenAPI dengan revisi proxy API. Lihat Tempat penyimpanan resource.

Konten apa yang divalidasi?

Tabel berikut merangkum konten pesan permintaan yang divalidasi oleh kebijakan OASValidation, menurut komponen.

Komponen	Minta validasi
Basepath	Memvalidasi basepath yang ditentukan oleh proxy API; mengabaikan basepath yang ditentukan dalam Spesifikasi OpenAPI.
Jalur	Memvalidasi bahwa jalur permintaan (minus basepath) cocok dengan salah satu pola jalur yang ditentukan dalam Spesifikasi OpenAPI.
Kata kerja	Memvalidasi bahwa kata kerja ditentukan untuk jalur dalam Spesifikasi OpenAPI.
Isi pesan permintaan	Memvalidasi keberadaan isi pesan dalam permintaan, jika diperlukan. Secara opsional, memvalidasi isi pesan terhadap skema isi permintaan operasi dalam Spesifikasi OpenAPI. Konfigurasi opsi ini menggunakan <ValidateMessageBody> Catatan: Kebijakan ini memvalidasi isi pesan permintaan terhadap Spesifikasi OpenAPI hanya jika Content-Type ditetapkan ke application/json. Jika jenis konten tidak disetel ke application/json, validasi isi pesan permintaan akan lulus secara otomatis (tanpa benar-benar memvalidasi konten).
Parameter	Memvalidasi bahwa parameter yang diperlukan ada dalam permintaan, termasuk parameter jalur, header, kueri, dan cookie. Memvalidasi bahwa nilai parameter cocok dengan yang ditentukan dalam Spesifikasi OpenAPI. Secara opsional, memvalidasi apakah ada parameter dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI. Konfigurasi opsi ini menggunakan <AllowUnspecifiedParameters>

Tabel berikut merangkum konten pesan respons yang divalidasi oleh kebijakan OASValidation, menurut komponen.

Komponen	Validasi respons
Jalur	Memvalidasi bahwa jalur permintaan (minus basepath) cocok dengan salah satu pola jalur yang ditentukan dalam Spesifikasi OpenAPI.
Kata kerja	Memvalidasi bahwa kata kerja ditentukan untuk jalur dalam Spesifikasi OpenAPI.
Isi pesan respons	Memvalidasi keberadaan isi pesan dalam respons, jika diperlukan. Memvalidasi bahwa header respons dalam Spesifikasi OpenAPI ada dalam pesan respons, dan nilai header respons cocok dengan skema. Secara opsional, memvalidasi isi pesan terhadap skema isi respons operasi dalam Spesifikasi OpenAPI. Konfigurasi opsi ini menggunakan <ValidateMessageBody>

Catatan: Kebijakan OASValidation Apigee memvalidasi jalur permintaan dan respons secara berbeda.
Untuk validasi permintaan, kebijakan ini memvalidasi jalur permintaan proxy API (misalnya, /hello untuk https://<BasePath>/hello).
Untuk validasi respons, kebijakan ini memvalidasi jalur endpoint target yang dipanggil Apigee (misalnya, /apigee/hello untuk https://{target-basepath}}/apigee/hello).
Perbedaan ini penting untuk diketahui jika jalur proxy dan target Anda berbeda, karena Anda harus menyelaraskan spesifikasi OpenAPI dengan tepat untuk validasi respons.

Sampel

Contoh berikut menunjukkan beberapa cara Anda dapat menggunakan kebijakan OASValidation untuk memvalidasi pesan terhadap Spesifikasi OpenAPI 3.0.

Memvalidasi pesan permintaan

Dalam contoh berikut, kebijakan myoaspolicy memvalidasi isi pesan permintaan terhadap skema isi pesan permintaan operasi yang ditentukan dalam Spesifikasi OpenAPI my-spec.json.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.json</OASResource>
   <Options>
      <ValidateMessageBody>true</ValidateMessageBody>
   </Options>
   <Source>request</Source>
</OASValidation>

Jika isi pesan tidak sesuai dengan Spesifikasi OpenAPI, error policies.oasvalidation.Failed akan ditampilkan.

Memvalidasi parameter

Contoh berikut mengonfigurasi kebijakan agar gagal jika parameter header, kueri, atau cookie ditentukan dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

Elemen <OASValidation>

Menentukan kebijakan Validasi Spesifikasi OpenAPI.

Nilai Default	Lihat tab Kebijakan Default di bawah
Wajib?	Wajib
Jenis	Objek kompleks
Elemen Induk	t/a
Elemen Turunan	<DisplayName> <OASResource> <Source> <Options> <Source>

Sintaksis

Elemen <OASValidation> menggunakan sintaksis berikut:

<OASValidation
  continueOnError="[true|false]"
  enabled="[true|false]"
  name="policy_name"
>
    <!-- All OASValidation child elements are optional except OASResource -->
    <DisplayName>policy_display_name</DisplayName>
    <OASResource>validation_JSON_or_YAML</OASResource>
    <Options>
        <ValidateMessageBody>[true|false]</ValidateMessageBody>
        <AllowUnspecifiedParameters>
            <Header>[true|false]</Header>
            <Query>[true|false]</Query>
            <Cookie>[true|false]</Cookie>
        </AllowUnspecifiedParameters>
    </Options>
    <Source>message_to_validate</Source>
</OASValidation>

Kebijakan Default

Contoh berikut menunjukkan setelan default saat Anda menambahkan kebijakan Validasi OAS ke alur Anda di UI Apigee:

<OASValidation continueOnError="false" enabled="true" name="OpenAPI-Spec-Validation-1">
    <DisplayName>OpenAPI Spec Validation-1</DisplayName>
    <Properties/>
    <Source>request</Source>
    <OASResource>oas://OpenAPI-Spec-Validation-1.yaml</OASResource>
</OASValidation>

Elemen ini memiliki atribut berikut yang umum untuk semua kebijakan:

Atribut	Default	Wajib?	Deskripsi
name	T/A	Wajib	Nama internal kebijakan. Nilai atribut name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter. Secara opsional, gunakan elemen <DisplayName> untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.
continueOnError	false	Opsional	Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Perilaku ini wajar terjadi untuk sebagian besar kebijakan. Tetapkan ke true agar eksekusi alur berlanjut meskipun setelah kebijakan gagal. Lihat juga: Aturan error HANYA dipicu dalam status error (tentang continueOnError) Menangani error dalam alur saat ini
enabled	benar	Opsional	Tetapkan ke true untuk menerapkan kebijakan. Tetapkan ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap terlampir ke alur.
async	false	Tidak digunakan lagi	Atribut ini tidak digunakan lagi.

Referensi elemen turunan

Bagian ini menjelaskan elemen turunan <OASValidation>.

<DisplayName>

Gunakan selain atribut name untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama yang berbeda dan lebih terdengar alami.

Elemen <DisplayName> umum untuk semua kebijakan.

Nilai Default	T/A
Wajib?	Opsional. Jika Anda menghilangkan <DisplayName>, nilai atribut name kebijakan akan digunakan.
Jenis	String
Elemen Induk	<PolicyElement>
Elemen Turunan	Tidak ada

Elemen <DisplayName> menggunakan sintaksis berikut:

Sintaks

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Contoh

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

Elemen <DisplayName> tidak memiliki atribut atau elemen turunan.

<OASResource>

Menentukan Spesifikasi OpenAPI yang akan divalidasi. Anda dapat menyimpan file ini:

• Di cakupan proxy API di bagian /apiproxy/resources/oas dalam paket proxy API
• Di bagian Resources pada tampilan Navigator editor proxy API.

Untuk mengetahui informasi selengkapnya, lihat Mengelola fasilitas.

Anda dapat menentukan Spesifikasi OpenAPI menggunakan template pesan, seperti {oas.resource.url}. Dalam hal ini, nilai variabel alur oas.resource.url (dalam tanda kurung kurawal) akan dievaluasi dan diganti ke dalam string payload saat runtime. Untuk mengetahui informasi selengkapnya, lihat Template pesan.

Nilai Default	Tidak ada
Wajib?	Wajib
Jenis	String
Elemen Induk	<OASValidation>
Elemen Turunan	Tidak ada

Sintaksis

Elemen <OASResource> menggunakan sintaksis berikut:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   ...
</OASValidation>

Contoh

Contoh berikut mereferensikan spesifikasi my-spec.yaml yang disimpan di /apiproxy/resources/oas dalam paket proxy API:

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
</OASValidation>

Elemen <OASResource> tidak memiliki atribut atau elemen turunan.

Catatan: Jika kebijakan OASValidation menentukan <OASResource> dengan persyaratan keamanan yang ditetapkan di tingkat global, persyaratan keamanan tidak akan diterapkan. Untuk memastikan penegakan, semua persyaratan keamanan harus ditetapkan di tingkat operasi dalam spesifikasi OpenAPI yang diteruskan dalam elemen <OASResource> kebijakan ini. Untuk mengetahui informasi selengkapnya, lihat Masalah Umum Apigee.

<Options>

Mengonfigurasi opsi untuk kebijakan.

Nilai Default	t/a
Wajib?	Opsional
Jenis	Jenis kompleks
Elemen Induk	<OASValidation>
Elemen Turunan	<ValidateMessageBody> <AllowUnspecifiedParameters>

Sintaksis

Elemen <Options> menggunakan sintaksis berikut:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <ValidateMessageBody>[true|false]</ValidateMessageBody>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
         <Query>[true|false]</Query>
         <Cookie>[true|false]</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Contoh

Contoh berikut mengonfigurasi opsi untuk kebijakan. Setiap opsi dijelaskan lebih mendetail di bawah.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <ValidateMessageBody>false</ValidateMessageBody>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<ValidateMessageBody>

Menentukan apakah kebijakan harus memvalidasi isi pesan terhadap skema isi permintaan operasi dalam Spesifikasi OpenAPI. Tetapkan ke true untuk memvalidasi isi pesan. Disetel ke false untuk memvalidasi hanya keberadaan isi pesan.

Anda dapat mengontrol apakah eksekusi alur berlanjut setelah terjadi error validasi dengan menetapkan atribut continueOnError untuk elemen <OASValidation> ke true.

Catatan: Kebijakan ini memvalidasi isi pesan permintaan terhadap Spesifikasi OpenAPI hanya jika Content-Type ditetapkan ke application/json. Jika jenis konten tidak disetel ke application/json, validasi isi pesan permintaan akan berhasil secara otomatis (tanpa benar-benar memvalidasi konten).

Nilai Default	false
Wajib?	Opsional
Jenis	Boolean
Elemen Induk	<Options>
Elemen Turunan	Tidak ada

Sintaksis

Elemen <ValidateMessageBody> menggunakan sintaksis berikut:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
         <ValidateMessageBody>[true|false]</ValidateMessageBody>
   </Options>
   ...
</OASValidation>

Contoh

Contoh berikut mengaktifkan validasi konten isi pesan:

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <ValidateMessageBody>true</ValidateMessageBody>
   </Options>
</OASValidation>

<AllowUnspecifiedParameters>

Mengonfigurasi perilaku kebijakan jika ada parameter header, kueri, atau cookie dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI.

Nilai Default	t/a
Wajib?	Opsional
Jenis	Jenis kompleks
Elemen Induk	<Options>
Elemen Turunan	<Header> <Query> <Cookie>

Sintaksis

Elemen <AllowUnspecifiedParameters> menggunakan sintaksis berikut:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
         <Query>[true|false]</Query>
         <Cookie>[true|false]</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Contoh

Contoh berikut mengonfigurasi kebijakan agar gagal jika parameter header, kueri, atau cookie ditentukan dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Header> (turunan dari <AllowUnspecifiedParameters>)

Mengonfigurasi perilaku kebijakan jika ada parameter header dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI.

Untuk mengizinkan parameter header ditentukan dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI, tetapkan parameter ini ke true. Jika tidak, tetapkan parameter ini ke false agar eksekusi kebijakan gagal.

Nilai Default	true
Wajib?	Boolean
Jenis	Jenis kompleks
Elemen Induk	<AllowUnspecifiedParameters>
Elemen Turunan	Tidak ada

Sintaksis

Elemen <Header> menggunakan sintaksis berikut:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Contoh

Contoh berikut mengonfigurasi kebijakan agar gagal jika parameter header ditentukan dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Query> (turunan dari <AllowUnspecifiedParameters>)

Mengonfigurasi perilaku kebijakan jika ada parameter kueri dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI.

Untuk mengizinkan parameter kueri ditentukan dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI, tetapkan parameter ini ke true. Jika tidak, tetapkan parameter ini ke false agar eksekusi kebijakan gagal.

Nilai Default	true
Wajib?	Boolean
Jenis	Jenis kompleks
Elemen Induk	<AllowUnspecifiedParameters>
Elemen Turunan	Tidak ada

Sintaksis

Elemen <Query> menggunakan sintaksis berikut:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Contoh

Contoh berikut mengonfigurasi kebijakan agar gagal jika parameter kueri ditentukan dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>false</Query>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Cookie> (turunan dari <AllowUnspecifiedParameters>)

Mengonfigurasi perilaku kebijakan jika ada parameter cookie dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI.

Untuk mengizinkan parameter cookie ditentukan dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI, tetapkan parameter ini ke true. Jika tidak, tetapkan parameter ini ke false agar eksekusi kebijakan gagal.

Nilai Default	true
Wajib?	Boolean
Jenis	Jenis kompleks
Elemen Induk	<AllowUnspecifiedParameters>
Elemen Turunan	Tidak ada

Sintaksis

Elemen <Cookie> menggunakan sintaksis berikut:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Contoh

Contoh berikut mengonfigurasi kebijakan agar gagal jika parameter kueri ditentukan dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Source>

Pesan JSON yang akan dievaluasi terhadap serangan payload JSON. Biasanya ditetapkan ke request, karena Anda biasanya perlu mengevaluasi permintaan masuk dari aplikasi klien. Setel ke response untuk mengevaluasi pesan respons. Disetel ke message untuk mengevaluasi pesan permintaan secara otomatis saat kebijakan dilampirkan ke alur permintaan dan pesan respons saat kebijakan dilampirkan ke alur respons.

Nilai Default	permintaan
Wajib?	Opsional
Jenis	String
Elemen Induk	<Source>
Elemen Turunan	Tidak ada

Sintaksis

Elemen <Source> menggunakan sintaksis berikut:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Source>[message|request|response]</Source>
   ...
</OASValidation>

Contoh

Contoh berikut mengevaluasi pesan permintaan secara otomatis saat kebijakan dilampirkan ke alur permintaan dan pesan respons saat kebijakan dilampirkan ke alur respons:

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Source>message</Source>
</OASValidation>

Elemen <Source> tidak memiliki atribut atau elemen turunan.

Skema untuk kebijakan ini

Setiap jenis kebijakan ditentukan oleh skema XML (.xsd). Sebagai referensi, skema kebijakan tersedia di GitHub.

Kode error

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
steps.oasvalidation.Failed	400	The Request message body cannot be validated against the provided OpenAPI Specification.
steps.oasvalidation.Failed	500	The Response message body cannot be validated against the provided OpenAPI Specification.
steps.oasvalidation.SourceMessageNotAvailable	500	Variable specified in the <Source> element of the policy is either out of scope or cannot be resolved.
steps.oasvalidation.NonMessageVariable	500	<Source> element is set to a variable that is not of type message.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause
ResourceDoesNotExist	OpenAPI Specification referenced in the <OASResource> element does not exist.
ResourceCompileFailed	OpenAPI Specification that is included in the deployment contains errors that prevent it from being compiled. This generally indicates that the specification is not a well-formed OpenAPI Specification 3.0.
BadResourceURL	OpenAPI Specification referenced in the <OASResource> element cannot be processed. This can occur if the file is not a JSON or YAML file or the file URL is not specified correctly.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variable	Description	Example
fault.category	The category of the fault. When the policy rejects a request, this will always hold Step.	fault.category = "Step"
fault.name	The name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "ResourceDoesNotExist"
fault.reason	The reason for the fault. It is a human-readable string explaining the reason for the fault.	OASValidation OAS-1 with resource "oas://my-spec1.yaml": failed with reason: "[ERROR - POST operation not allowed on path '/persons/13'.: []]"
fault.subcategory	The subcategory of the fault. When the policy rejects a request, this will always hold OASValidationFailure.	fault.subcategory = "OASValidationFailure"
OASValidation.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	OASValidation.myoaspolicy.failed = true

Fitur Spesifikasi OpenAPI yang didukung

Kebijakan OASValidation mendukung fitur Spesifikasi OpenAPI yang dirangkum dalam tabel berikut, menurut kategori. Fitur yang tidak didukung juga tercantum.

Catatan: Kebijakan OASValidation akan menolak Spesifikasi OpenAPI yang menggunakan fitur yang tidak didukung. Dalam hal ini, kebijakan tidak akan lulus validasi fitur yang tidak didukung dan deployment proxy API akan gagal.

Kategori	Didukung	Tidak didukung
Format jenis data	boolean date date-time double email float int32/int64 ipv4/ipv6 md5 sha1/sha256/sha512 string uri uri-template uuid	biner byte sandi
Objek diskriminator	mapping propertyName	T/A
Objek jenis media	schema	encoding contoh contoh
Objek operasi	parameters requestBody responses security (dukungan sebagian)	callback tidak digunakan lagi server
Objek parameter	allowEmptyValue in (query, header, path) required responses schema style (deepObject, form, formmatrix, label, pipeDelimited, simple, spaceDelimited) Catatan: deepObject hanya mendukung parameter string; array dan objek bertingkat tidak didukung.	allowReserved deprecated example examples content
Objek jalur	delete get head options parameters patch post put trace variables	server
Objek isi permintaan	application/json application/hal+json application/x-www-form-urlencoded (objek encoding tidak didukung) content required	application/xml multipart/form-data text/plain text/xml
Objek respons	application/json application/hal+json application/x-www-form-urlencoded (objek encoding tidak didukung) content headers	application/xml links text/plain text/xml
Objek respons	default Kode Status HTTP	T/A
Objek skema	$ref additionalProperties (hanya varian tanda boolean) allOf (diabaikan jika additionalProperties adalah false) anyOf enum exclusiveMaximum/exclusiveMinimum format items maximum/minimum maxItems/minItems maxLength/minLength maxProperties/minProperties multipleOf not nullable oneOf pattern properties required title type uniqueItems	tidak digunakan lagi contoh readOnly writeOnly xml
Objek skema keamanan	in (header, query) (diabaikan jika type adalah http) name type (apiKey, http)	bearerFormat flows openIdConnectUrl scheme
Objek server	url variables	Beberapa definisi server

Menggunakan pola dalam skema

Standar Spesifikasi OpenAPI memungkinkan spesifikasi menetapkan schema untuk menjelaskan jenis data parameter atau kolom. Untuk parameter atau kolom jenis string, skema juga dapat menentukan pattern, yang merupakan ekspresi reguler (regex) yang menentukan bentuk yang valid untuk string.

Sebagai contoh, perhatikan fragmen Spesifikasi OpenAPI berikut:

paths:
  /products/{product-id}:
    get:
      operationId: getProduct
      summary: Get product by id
      description: returns information regarding a product, by id
      parameters:
        - name: product-id
          in: path
          description: id of the product
          required: true
          schema:
            type: string
            pattern: '^\w{3}-\d{4}$'

Spesifikasi ini mengharuskan bahwa untuk operasi getProduct, parameter product-id harus mematuhi ekspresi reguler yang diberikan, yang menetapkan urutan 3 karakter kata, tanda hubung, dan 4 digit desimal.

Spesifikasi OpenAPI mengacu pada standar Validasi Skema JSON untuk secara formal menentukan perilaku pola dalam memvalidasi nilai string, dan pada standar Inti Skema JSON untuk rekomendasi kepada penulis skema terkait kumpulan sintaks ekspresi reguler yang dibatasi. Standar tersebut merekomendasikan untuk menghindari penggunaan lookaround (lookahead dan lookbehind), backreference, dan ekspresi karakter oktal, serta fitur lainnya, dalam pola di dalam dokumen Spesifikasi OpenAPI.

Secara default, Apigee memvalidasi dokumen Spesifikasi OpenAPI yang dirujuk oleh kebijakan OASValidation dan melaporkan error jika dokumen spesifikasi tidak dibuat dengan baik. Apigee juga memvalidasi pola regex dalam dokumen spesifikasi Anda dan melaporkan masalah yang ditemukan di sana.

Penting untuk diperhatikan bahwa jika Anda menggunakan fitur regex di luar subset yang direkomendasikan, Apigee tidak akan memvalidasi regex dan akan menangguhkan validasi tambahan apa pun pada dokumen Spesifikasi OpenAPI Anda. Jika ada error dalam dokumen, atau dalam regex yang menggunakan fitur di luar subset yang direkomendasikan, atau jika fitur regex tidak didukung oleh runtime Apigee, error hanya akan terdeteksi saat runtime ketika kebijakan dijalankan.

Tabel berikut memberikan beberapa contoh.

Pola	Perilaku
^\w{3}-\d{4}$	Pola valid. Hanya menggunakan fitur regex dalam subset yang direkomendasikan. Apigee akan mengizinkan penyimpanan atau impor proxy, dan saat runtime, kebijakan OASValidation akan berfungsi sebagaimana mestinya, memvalidasi parameter terhadap pola.
^([a-z]\w{3}-\d{4}$	Pola tidak valid; tidak ada tanda kurung tutup. Pola tidak menggunakan fitur regex di luar subset yang direkomendasikan. Apigee akan melaporkan error ini saat Anda mengimpor atau menyimpan proxy API.
^(?![a-z]\w{3}-\d{4}$	Pola tidak valid. Seperti contoh sebelumnya, tanda kurung penutupnya tidak ada. Namun, Apigee tidak akan melaporkan error ini saat Anda menyimpan atau mengimpor Proxy API, karena regex menggunakan lookahead negatif, yang berada di luar subset fitur regex yang direkomendasikan. Error hanya akan terdeteksi saat runtime ketika kebijakan dijalankan.
^(?![a-z])\w{3}-\d{4}$	Pola valid, tetapi menggunakan lookahead negatif, yang berada di luar subset fitur regex yang direkomendasikan. Apigee akan menangguhkan validasi dokumen Spesifikasi OpenAPI. Saat runtime, saat Anda menjalankan kebijakan OASValidation yang mereferensikan spesifikasi menggunakan pola ini, karena runtime Apigee sebenarnya mendukung lookahead negatif, Apigee akan menerapkan regex ini dengan benar untuk memvalidasi nilai parameter.
^(a)?b(?(1)c|d)$	Pola valid, tetapi menggunakan kondisi grup pengambilan, yang berada di luar subset fitur regex yang direkomendasikan. Apigee akan menangguhkan validasi dokumen Spesifikasi OpenAPI. Saat runtime, saat Anda menjalankan kebijakan OASValidation yang mereferensikan spesifikasi menggunakan pola ini, karena runtime Apigee tidak mendukung fitur regex ini, Apigee akan menampilkan error.

Sebaiknya gunakan hanya subset fitur yang direkomendasikan dalam regex Anda untuk mencegah kegagalan runtime.

Topik terkait

• Kebijakan perlindungan Ancaman JSON
• Kebijakan SOAPMessageValidation