From c94a741c6370df21886149749b2d0246a839e3a7 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 2 May 2024 03:34:50 +0000 Subject: [PATCH] Deploy to GitHub pages --- assets/app.d3800f98.js | 32 ++ assets/guide_annotations.md.b48e8efc.js | 76 +++ assets/guide_annotations.md.b48e8efc.lean.js | 1 + assets/guide_attributes.md.b0468df2.js | 13 + assets/guide_attributes.md.b0468df2.lean.js | 1 + assets/guide_common-techniques.md.c3d11b39.js | 216 ++++++++ ...uide_common-techniques.md.c3d11b39.lean.js | 1 + assets/guide_cookbook.md.58253880.js | 496 +++++++++++++++++ assets/guide_cookbook.md.58253880.lean.js | 38 ++ assets/guide_faq.md.818b1e6e.js | 88 +++ assets/guide_faq.md.818b1e6e.lean.js | 1 + ...enerating-openapi-documents.md.4e871b91.js | 30 + ...ting-openapi-documents.md.4e871b91.lean.js | 1 + assets/guide_index.md.2455f0b6.js | 1 + assets/guide_index.md.2455f0b6.lean.js | 1 + assets/guide_installation.md.c1a9b9e5.js | 3 + assets/guide_installation.md.c1a9b9e5.lean.js | 1 + assets/guide_migrating-to-v3.md.f8a7ce6f.js | 1 + .../guide_migrating-to-v3.md.f8a7ce6f.lean.js | 1 + assets/guide_migrating-to-v4.md.5a3b1acb.js | 48 ++ .../guide_migrating-to-v4.md.5a3b1acb.lean.js | 1 + assets/guide_required-elements.md.13284533.js | 66 +++ ...uide_required-elements.md.13284533.lean.js | 55 ++ assets/guide_under-the-hood.md.19c62cc3.js | 3 + .../guide_under-the-hood.md.19c62cc3.lean.js | 1 + assets/index.md.59a0a95e.js | 57 ++ assets/index.md.59a0a95e.lean.js | 55 ++ assets/reference_annotations.md.cdba131a.js | 1 + .../reference_annotations.md.cdba131a.lean.js | 1 + assets/reference_attributes.md.e96acd84.js | 1 + .../reference_attributes.md.e96acd84.lean.js | 1 + assets/reference_generator.md.681f1e2d.js | 80 +++ .../reference_generator.md.681f1e2d.lean.js | 1 + assets/reference_index.md.c170f535.js | 1 + assets/reference_index.md.c170f535.lean.js | 1 + assets/reference_processors.md.6f2ce137.js | 1 + .../reference_processors.md.6f2ce137.lean.js | 1 + assets/related-projects.md.2420d622.js | 1 + assets/related-projects.md.2420d622.lean.js | 1 + assets/style.29d805fc.css | 1 + guide/annotations.html | 96 ++++ guide/attributes.html | 33 ++ guide/common-techniques.html | 236 ++++++++ guide/cookbook.html | 516 ++++++++++++++++++ guide/faq.html | 108 ++++ guide/generating-openapi-documents.html | 50 ++ guide/index.html | 21 + guide/installation.html | 23 + guide/migrating-to-v3.html | 21 + guide/migrating-to-v4.html | 68 +++ guide/required-elements.html | 86 +++ guide/under-the-hood.html | 23 + hashmap.json | 1 + index.html | 77 +++ reference/annotations.html | 21 + reference/attributes.html | 21 + reference/generator.html | 100 ++++ reference/index.html | 21 + reference/processors.html | 21 + related-projects.html | 21 + 60 files changed, 2944 insertions(+) create mode 100644 assets/app.d3800f98.js create mode 100644 assets/guide_annotations.md.b48e8efc.js create mode 100644 assets/guide_annotations.md.b48e8efc.lean.js create mode 100644 assets/guide_attributes.md.b0468df2.js create mode 100644 assets/guide_attributes.md.b0468df2.lean.js create mode 100644 assets/guide_common-techniques.md.c3d11b39.js create mode 100644 assets/guide_common-techniques.md.c3d11b39.lean.js create mode 100644 assets/guide_cookbook.md.58253880.js create mode 100644 assets/guide_cookbook.md.58253880.lean.js create mode 100644 assets/guide_faq.md.818b1e6e.js create mode 100644 assets/guide_faq.md.818b1e6e.lean.js create mode 100644 assets/guide_generating-openapi-documents.md.4e871b91.js create mode 100644 assets/guide_generating-openapi-documents.md.4e871b91.lean.js create mode 100644 assets/guide_index.md.2455f0b6.js create mode 100644 assets/guide_index.md.2455f0b6.lean.js create mode 100644 assets/guide_installation.md.c1a9b9e5.js create mode 100644 assets/guide_installation.md.c1a9b9e5.lean.js create mode 100644 assets/guide_migrating-to-v3.md.f8a7ce6f.js create mode 100644 assets/guide_migrating-to-v3.md.f8a7ce6f.lean.js create mode 100644 assets/guide_migrating-to-v4.md.5a3b1acb.js create mode 100644 assets/guide_migrating-to-v4.md.5a3b1acb.lean.js create mode 100644 assets/guide_required-elements.md.13284533.js create mode 100644 assets/guide_required-elements.md.13284533.lean.js create mode 100644 assets/guide_under-the-hood.md.19c62cc3.js create mode 100644 assets/guide_under-the-hood.md.19c62cc3.lean.js create mode 100644 assets/index.md.59a0a95e.js create mode 100644 assets/index.md.59a0a95e.lean.js create mode 100644 assets/reference_annotations.md.cdba131a.js create mode 100644 assets/reference_annotations.md.cdba131a.lean.js create mode 100644 assets/reference_attributes.md.e96acd84.js create mode 100644 assets/reference_attributes.md.e96acd84.lean.js create mode 100644 assets/reference_generator.md.681f1e2d.js create mode 100644 assets/reference_generator.md.681f1e2d.lean.js create mode 100644 assets/reference_index.md.c170f535.js create mode 100644 assets/reference_index.md.c170f535.lean.js create mode 100644 assets/reference_processors.md.6f2ce137.js create mode 100644 assets/reference_processors.md.6f2ce137.lean.js create mode 100644 assets/related-projects.md.2420d622.js create mode 100644 assets/related-projects.md.2420d622.lean.js create mode 100644 assets/style.29d805fc.css create mode 100644 guide/annotations.html create mode 100644 guide/attributes.html create mode 100644 guide/common-techniques.html create mode 100644 guide/cookbook.html create mode 100644 guide/faq.html create mode 100644 guide/generating-openapi-documents.html create mode 100644 guide/index.html create mode 100644 guide/installation.html create mode 100644 guide/migrating-to-v3.html create mode 100644 guide/migrating-to-v4.html create mode 100644 guide/required-elements.html create mode 100644 guide/under-the-hood.html create mode 100644 hashmap.json create mode 100644 index.html create mode 100644 reference/annotations.html create mode 100644 reference/attributes.html create mode 100644 reference/generator.html create mode 100644 reference/index.html create mode 100644 reference/processors.html create mode 100644 related-projects.html diff --git a/assets/app.d3800f98.js b/assets/app.d3800f98.js new file mode 100644 index 000000000..7324d71df --- /dev/null +++ b/assets/app.d3800f98.js @@ -0,0 +1,32 @@ +const ri="modulepreload",js={},oi="/swagger-php/",ii=function(t,n){return!n||n.length===0?t():Promise.all(n.map(s=>{if(s=`${oi}${s}`,s in js)return;js[s]=!0;const r=s.endsWith(".css"),o=r?'[rel="stylesheet"]':"";if(document.querySelector(`link[href="${s}"]${o}`))return;const i=document.createElement("link");if(i.rel=r?"stylesheet":ri,r||(i.as="script",i.crossOrigin=""),i.href=s,document.head.appendChild(i),r)return new Promise((l,a)=>{i.addEventListener("load",l),i.addEventListener("error",()=>a(new Error(`Unable to preload CSS for ${s}`)))})})).then(()=>t())};/** +* @vue/shared v3.4.26 +* (c) 2018-present Yuxi (Evan) You and Vue contributors +* @license MIT +**//*! #__NO_SIDE_EFFECTS__ */function Pt(e,t){const n=new Set(e.split(","));return t?s=>n.has(s.toLowerCase()):s=>n.has(s)}const ee={},kt=[],Ee=()=>{},li=()=>!1,Xt=e=>e.charCodeAt(0)===111&&e.charCodeAt(1)===110&&(e.charCodeAt(2)>122||e.charCodeAt(2)<97),us=e=>e.startsWith("onUpdate:"),_e=Object.assign,fs=(e,t)=>{const n=e.indexOf(t);n>-1&&e.splice(n,1)},ai=Object.prototype.hasOwnProperty,Y=(e,t)=>ai.call(e,t),N=Array.isArray,Ct=e=>In(e)==="[object Map]",Pr=e=>In(e)==="[object Set]",U=e=>typeof e=="function",le=e=>typeof e=="string",gt=e=>typeof e=="symbol",ne=e=>e!==null&&typeof e=="object",Rr=e=>(ne(e)||U(e))&&U(e.then)&&U(e.catch),Or=Object.prototype.toString,In=e=>Or.call(e),ci=e=>In(e).slice(8,-1),Hr=e=>In(e)==="[object Object]",ds=e=>le(e)&&e!=="NaN"&&e[0]!=="-"&&""+parseInt(e,10)===e,St=Pt(",key,ref,ref_for,ref_key,onVnodeBeforeMount,onVnodeMounted,onVnodeBeforeUpdate,onVnodeUpdated,onVnodeBeforeUnmount,onVnodeUnmounted"),En=e=>{const t=Object.create(null);return n=>t[n]||(t[n]=e(n))},ui=/-(\w)/g,Ke=En(e=>e.replace(ui,(t,n)=>n?n.toUpperCase():"")),fi=/\B([A-Z])/g,vt=En(e=>e.replace(fi,"-$1").toLowerCase()),Ln=En(e=>e.charAt(0).toUpperCase()+e.slice(1)),Wn=En(e=>e?`on${Ln(e)}`:""),it=(e,t)=>!Object.is(e,t),Kn=(e,t)=>{for(let n=0;n{Object.defineProperty(e,t,{configurable:!0,enumerable:!1,writable:s,value:n})},di=e=>{const t=parseFloat(e);return isNaN(t)?e:t};let Bs;const hs=()=>Bs||(Bs=typeof globalThis!="undefined"?globalThis:typeof self!="undefined"?self:typeof window!="undefined"?window:typeof global!="undefined"?global:{});function Pn(e){if(N(e)){const t={};for(let n=0;n{if(n){const s=n.split(pi);s.length>1&&(t[s[0].trim()]=s[1].trim())}}),t}function gi(e){let t="";if(!e||le(e))return t;for(const n in e){const s=e[n],r=n.startsWith("--")?n:vt(n);(le(s)||typeof s=="number")&&(t+=`${r}:${s};`)}return t}function Ce(e){let t="";if(le(e))t=e;else if(N(e))for(let n=0;nle(e)?e:e==null?"":N(e)||ne(e)&&(e.toString===Or||!U(e.toString))?JSON.stringify(e,Nr,2):String(e),Nr=(e,t)=>t&&t.__v_isRef?Nr(e,t.value):Ct(t)?{[`Map(${t.size})`]:[...t.entries()].reduce((n,[s,r],o)=>(n[qn(s,o)+" =>"]=r,n),{})}:Pr(t)?{[`Set(${t.size})`]:[...t.values()].map(n=>qn(n))}:gt(t)?qn(t):ne(t)&&!N(t)&&!Hr(t)?String(t):t,qn=(e,t="")=>{var n;return gt(e)?`Symbol(${(n=e.description)!=null?n:t})`:e};/** +* @vue/reactivity v3.4.26 +* (c) 2018-present Yuxi (Evan) You and Vue contributors +* @license MIT +**/let Oe;class wi{constructor(t=!1){this.detached=t,this._active=!0,this.effects=[],this.cleanups=[],this.parent=Oe,!t&&Oe&&(this.index=(Oe.scopes||(Oe.scopes=[])).push(this)-1)}get active(){return this._active}run(t){if(this._active){const n=Oe;try{return Oe=this,t()}finally{Oe=n}}}on(){Oe=this}off(){Oe=this.parent}stop(t){if(this._active){let n,s;for(n=0,s=this.effects.length;n=4))break}this._dirtyLevel===1&&(this._dirtyLevel=0),Ze()}return this._dirtyLevel>=4}set dirty(t){this._dirtyLevel=t?4:0}run(){if(this._dirtyLevel=0,!this.active)return this.fn();let t=ot,n=dt;try{return ot=!0,dt=this,this._runnings++,Ws(this),this.fn()}finally{Ks(this),this._runnings--,dt=n,ot=t}}stop(){this.active&&(Ws(this),Ks(this),this.onStop&&this.onStop(),this.active=!1)}}function Si(e){return e.value}function Ws(e){e._trackId++,e._depsLength=0}function Ks(e){if(e.deps.length>e._depsLength){for(let t=e._depsLength;t{const n=new Map;return n.cleanup=e,n.computed=t,n},gn=new WeakMap,ht=Symbol(""),ns=Symbol("");function Ae(e,t,n){if(ot&&dt){let s=gn.get(e);s||gn.set(e,s=new Map);let r=s.get(n);r||s.set(n,r=Vr(()=>s.delete(n))),jr(dt,r)}}function Ye(e,t,n,s,r,o){const i=gn.get(e);if(!i)return;let l=[];if(t==="clear")l=[...i.values()];else if(n==="length"&&N(e)){const a=Number(s);i.forEach((u,d)=>{(d==="length"||!gt(d)&&d>=a)&&l.push(u)})}else switch(n!==void 0&&l.push(i.get(n)),t){case"add":N(e)?ds(n)&&l.push(i.get("length")):(l.push(i.get(ht)),Ct(e)&&l.push(i.get(ns)));break;case"delete":N(e)||(l.push(i.get(ht)),Ct(e)&&l.push(i.get(ns)));break;case"set":Ct(e)&&l.push(i.get(ht));break}ms();for(const a of l)a&&Br(a,4);gs()}function Ti(e,t){const n=gn.get(e);return n&&n.get(t)}const $i=Pt("__proto__,__v_isRef,__isVue"),Wr=new Set(Object.getOwnPropertyNames(Symbol).filter(e=>e!=="arguments"&&e!=="caller").map(e=>Symbol[e]).filter(gt)),qs=Ai();function Ai(){const e={};return["includes","indexOf","lastIndexOf"].forEach(t=>{e[t]=function(...n){const s=G(this);for(let o=0,i=this.length;o{e[t]=function(...n){Xe(),ms();const s=G(this)[t].apply(this,n);return gs(),Ze(),s}}),e}function Ii(e){gt(e)||(e=String(e));const t=G(this);return Ae(t,"has",e),t.hasOwnProperty(e)}class Kr{constructor(t=!1,n=!1){this._isReadonly=t,this._isShallow=n}get(t,n,s){const r=this._isReadonly,o=this._isShallow;if(n==="__v_isReactive")return!r;if(n==="__v_isReadonly")return r;if(n==="__v_isShallow")return o;if(n==="__v_raw")return s===(r?o?Bi:Gr:o?Yr:zr).get(t)||Object.getPrototypeOf(t)===Object.getPrototypeOf(s)?t:void 0;const i=N(t);if(!r){if(i&&Y(qs,n))return Reflect.get(qs,n,s);if(n==="hasOwnProperty")return Ii}const l=Reflect.get(t,n,s);return(gt(n)?Wr.has(n):$i(n))||(r||Ae(t,"get",n),o)?l:we(l)?i&&ds(n)?l:l.value:ne(l)?r?Jr(l):Rt(l):l}}class qr extends Kr{constructor(t=!1){super(!1,t)}set(t,n,s,r){let o=t[n];if(!this._isShallow){const a=qt(o);if(!vn(s)&&!qt(s)&&(o=G(o),s=G(s)),!N(t)&&we(o)&&!we(s))return a?!1:(o.value=s,!0)}const i=N(t)&&ds(n)?Number(n)e,Rn=e=>Reflect.getPrototypeOf(e);function sn(e,t,n=!1,s=!1){e=e.__v_raw;const r=G(e),o=G(t);n||(it(t,o)&&Ae(r,"get",t),Ae(r,"get",o));const{has:i}=Rn(r),l=s?vs:n?xs:zt;if(i.call(r,t))return l(e.get(t));if(i.call(r,o))return l(e.get(o));e!==r&&e.get(t)}function rn(e,t=!1){const n=this.__v_raw,s=G(n),r=G(e);return t||(it(e,r)&&Ae(s,"has",e),Ae(s,"has",r)),e===r?n.has(e):n.has(e)||n.has(r)}function on(e,t=!1){return e=e.__v_raw,!t&&Ae(G(e),"iterate",ht),Reflect.get(e,"size",e)}function zs(e){e=G(e);const t=G(this);return Rn(t).has.call(t,e)||(t.add(e),Ye(t,"add",e,e)),this}function Ys(e,t){t=G(t);const n=G(this),{has:s,get:r}=Rn(n);let o=s.call(n,e);o||(e=G(e),o=s.call(n,e));const i=r.call(n,e);return n.set(e,t),o?it(t,i)&&Ye(n,"set",e,t):Ye(n,"add",e,t),this}function Gs(e){const t=G(this),{has:n,get:s}=Rn(t);let r=n.call(t,e);r||(e=G(e),r=n.call(t,e)),s&&s.call(t,e);const o=t.delete(e);return r&&Ye(t,"delete",e,void 0),o}function Js(){const e=G(this),t=e.size!==0,n=e.clear();return t&&Ye(e,"clear",void 0,void 0),n}function ln(e,t){return function(s,r){const o=this,i=o.__v_raw,l=G(i),a=t?vs:e?xs:zt;return!e&&Ae(l,"iterate",ht),i.forEach((u,d)=>s.call(r,a(u),a(d),o))}}function an(e,t,n){return function(...s){const r=this.__v_raw,o=G(r),i=Ct(o),l=e==="entries"||e===Symbol.iterator&&i,a=e==="keys"&&i,u=r[e](...s),d=n?vs:t?xs:zt;return!t&&Ae(o,"iterate",a?ns:ht),{next(){const{value:p,done:b}=u.next();return b?{value:p,done:b}:{value:l?[d(p[0]),d(p[1])]:d(p),done:b}},[Symbol.iterator](){return this}}}}function et(e){return function(...t){return e==="delete"?!1:e==="clear"?void 0:this}}function Oi(){const e={get(o){return sn(this,o)},get size(){return on(this)},has:rn,add:zs,set:Ys,delete:Gs,clear:Js,forEach:ln(!1,!1)},t={get(o){return sn(this,o,!1,!0)},get size(){return on(this)},has:rn,add:zs,set:Ys,delete:Gs,clear:Js,forEach:ln(!1,!0)},n={get(o){return sn(this,o,!0)},get size(){return on(this,!0)},has(o){return rn.call(this,o,!0)},add:et("add"),set:et("set"),delete:et("delete"),clear:et("clear"),forEach:ln(!0,!1)},s={get(o){return sn(this,o,!0,!0)},get size(){return on(this,!0)},has(o){return rn.call(this,o,!0)},add:et("add"),set:et("set"),delete:et("delete"),clear:et("clear"),forEach:ln(!0,!0)};return["keys","values","entries",Symbol.iterator].forEach(o=>{e[o]=an(o,!1,!1),n[o]=an(o,!0,!1),t[o]=an(o,!1,!0),s[o]=an(o,!0,!0)}),[e,n,t,s]}const[Hi,Mi,Di,Ni]=Oi();function bs(e,t){const n=t?e?Ni:Di:e?Mi:Hi;return(s,r,o)=>r==="__v_isReactive"?!e:r==="__v_isReadonly"?e:r==="__v_raw"?s:Reflect.get(Y(n,r)&&r in s?n:s,r,o)}const Fi={get:bs(!1,!1)},Ui={get:bs(!1,!0)},ji={get:bs(!0,!1)};const zr=new WeakMap,Yr=new WeakMap,Gr=new WeakMap,Bi=new WeakMap;function Vi(e){switch(e){case"Object":case"Array":return 1;case"Map":case"Set":case"WeakMap":case"WeakSet":return 2;default:return 0}}function Wi(e){return e.__v_skip||!Object.isExtensible(e)?0:Vi(ci(e))}function Rt(e){return qt(e)?e:ys(e,!1,Li,Fi,zr)}function Ki(e){return ys(e,!1,Ri,Ui,Yr)}function Jr(e){return ys(e,!0,Pi,ji,Gr)}function ys(e,t,n,s,r){if(!ne(e)||e.__v_raw&&!(t&&e.__v_isReactive))return e;const o=r.get(e);if(o)return o;const i=Wi(e);if(i===0)return e;const l=new Proxy(e,i===2?s:n);return r.set(e,l),l}function Ut(e){return qt(e)?Ut(e.__v_raw):!!(e&&e.__v_isReactive)}function qt(e){return!!(e&&e.__v_isReadonly)}function vn(e){return!!(e&&e.__v_isShallow)}function Xr(e){return e?!!e.__v_raw:!1}function G(e){const t=e&&e.__v_raw;return t?G(t):e}function hn(e){return Object.isExtensible(e)&&Mr(e,"__v_skip",!0),e}const zt=e=>ne(e)?Rt(e):e,xs=e=>ne(e)?Jr(e):e;class Zr{constructor(t,n,s,r){this.getter=t,this._setter=n,this.dep=void 0,this.__v_isRef=!0,this.__v_isReadonly=!1,this.effect=new _s(()=>t(this._value),()=>pn(this,this.effect._dirtyLevel===2?2:3)),this.effect.computed=this,this.effect.active=this._cacheable=!r,this.__v_isReadonly=s}get value(){const t=G(this);return(!t._cacheable||t.effect.dirty)&&it(t._value,t._value=t.effect.run())&&pn(t,4),Qr(t),t.effect._dirtyLevel>=2&&pn(t,2),t._value}set value(t){this._setter(t)}get _dirty(){return this.effect.dirty}set _dirty(t){this.effect.dirty=t}}function qi(e,t,n=!1){let s,r;const o=U(e);return o?(s=e,r=Ee):(s=e.get,r=e.set),new Zr(s,r,o||!r,n)}function Qr(e){var t;ot&&dt&&(e=G(e),jr(dt,(t=e.dep)!=null?t:e.dep=Vr(()=>e.dep=void 0,e instanceof Zr?e:void 0)))}function pn(e,t=4,n){e=G(e);const s=e.dep;s&&Br(s,t)}function we(e){return!!(e&&e.__v_isRef===!0)}function _t(e){return eo(e,!1)}function zi(e){return eo(e,!0)}function eo(e,t){return we(e)?e:new Yi(e,t)}class Yi{constructor(t,n){this.__v_isShallow=n,this.dep=void 0,this.__v_isRef=!0,this._rawValue=n?t:G(t),this._value=n?t:zt(t)}get value(){return Qr(this),this._value}set value(t){const n=this.__v_isShallow||vn(t)||qt(t);t=n?t:G(t),it(t,this._rawValue)&&(this._rawValue=t,this._value=n?t:zt(t),pn(this,4))}}function $(e){return we(e)?e.value:e}const Gi={get:(e,t,n)=>$(Reflect.get(e,t,n)),set:(e,t,n,s)=>{const r=e[t];return we(r)&&!we(n)?(r.value=n,!0):Reflect.set(e,t,n,s)}};function to(e){return Ut(e)?e:new Proxy(e,Gi)}function ws(e){const t=N(e)?new Array(e.length):{};for(const n in e)t[n]=Xi(e,n);return t}class Ji{constructor(t,n,s){this._object=t,this._key=n,this._defaultValue=s,this.__v_isRef=!0}get value(){const t=this._object[this._key];return t===void 0?this._defaultValue:t}set value(t){this._object[this._key]=t}get dep(){return Ti(G(this._object),this._key)}}function Xi(e,t,n){const s=e[t];return we(s)?s:new Ji(e,t,n)}/** +* @vue/runtime-core v3.4.26 +* (c) 2018-present Yuxi (Evan) You and Vue contributors +* @license MIT +**/const jt=[];function tt(e,...t){Xe();const n=jt.length?jt[jt.length-1].component:null,s=n&&n.appContext.config.warnHandler,r=Zi();if(s)Ge(s,n,11,[e+t.map(o=>{var i,l;return(l=(i=o.toString)==null?void 0:i.call(o))!=null?l:JSON.stringify(o)}).join(""),n&&n.proxy,r.map(({vnode:o})=>`at <${Do(n,o.type)}>`).join(` +`),r]);else{const o=[`[Vue warn]: ${e}`,...t];r.length&&o.push(` +`,...Qi(r)),console.warn(...o)}Ze()}function Zi(){let e=jt[jt.length-1];if(!e)return[];const t=[];for(;e;){const n=t[0];n&&n.vnode===e?n.recurseCount++:t.push({vnode:e,recurseCount:0});const s=e.component&&e.component.parent;e=s&&s.vnode}return t}function Qi(e){const t=[];return e.forEach((n,s)=>{t.push(...s===0?[]:[` +`],...el(n))}),t}function el({vnode:e,recurseCount:t}){const n=t>0?`... (${t} recursive calls)`:"",s=e.component?e.component.parent==null:!1,r=` at <${Do(e.component,e.type,s)}`,o=">"+n;return e.props?[r,...tl(e.props),o]:[r+o]}function tl(e){const t=[],n=Object.keys(e);return n.slice(0,3).forEach(s=>{t.push(...no(s,e[s]))}),n.length>3&&t.push(" ..."),t}function no(e,t,n){return le(t)?(t=JSON.stringify(t),n?t:[`${e}=${t}`]):typeof t=="number"||typeof t=="boolean"||t==null?n?t:[`${e}=${t}`]:we(t)?(t=no(e,G(t.value),!0),n?t:[`${e}=Ref<`,t,">"]):U(t)?[`${e}=fn${t.name?`<${t.name}>`:""}`]:(t=G(t),n?t:[`${e}=`,t])}function Ge(e,t,n,s){try{return s?e(...s):e()}catch(r){On(r,t,n)}}function Ne(e,t,n,s){if(U(e)){const r=Ge(e,t,n,s);return r&&Rr(r)&&r.catch(o=>{On(o,t,n)}),r}if(N(e)){const r=[];for(let o=0;o>>1,r=be[s],o=Gt(r);oVe&&be.splice(t,1)}function ol(e){N(e)?Tt.push(...e):(!nt||!nt.includes(e,e.allowRecurse?ut+1:ut))&&Tt.push(e),oo()}function Xs(e,t,n=Yt?Ve+1:0){for(;nGt(n)-Gt(s));if(Tt.length=0,nt){nt.push(...t);return}for(nt=t,ut=0;ute.id==null?1/0:e.id,il=(e,t)=>{const n=Gt(e)-Gt(t);if(n===0){if(e.pre&&!t.pre)return-1;if(t.pre&&!e.pre)return 1}return n};function io(e){ss=!1,Yt=!0,be.sort(il);const t=Ee;try{for(Ve=0;Vele(C)?C.trim():C)),p&&(r=n.map(di))}let l,a=s[l=Wn(t)]||s[l=Wn(Ke(t))];!a&&o&&(a=s[l=Wn(vt(t))]),a&&Ne(a,e,6,r);const u=s[l+"Once"];if(u){if(!e.emitted)e.emitted={};else if(e.emitted[l])return;e.emitted[l]=!0,Ne(u,e,6,r)}}function lo(e,t,n=!1){const s=t.emitsCache,r=s.get(e);if(r!==void 0)return r;const o=e.emits;let i={},l=!1;if(!U(e)){const a=u=>{const d=lo(u,t,!0);d&&(l=!0,_e(i,d))};!n&&t.mixins.length&&t.mixins.forEach(a),e.extends&&a(e.extends),e.mixins&&e.mixins.forEach(a)}return!o&&!l?(ne(e)&&s.set(e,null),null):(N(o)?o.forEach(a=>i[a]=null):_e(i,o),ne(e)&&s.set(e,i),i)}function Hn(e,t){return!e||!Xt(t)?!1:(t=t.slice(2).replace(/Once$/,""),Y(e,t[0].toLowerCase()+t.slice(1))||Y(e,vt(t))||Y(e,t))}let pe=null,Mn=null;function yn(e){const t=pe;return pe=e,Mn=e&&e.type.__scopeId||null,t}function Ss(e){Mn=e}function Ts(){Mn=null}function Pe(e,t=pe,n){if(!t||e._n)return e;const s=(...r)=>{s._d&&ur(-1);const o=yn(t);let i;try{i=e(...r)}finally{yn(o),s._d&&ur(1)}return i};return s._n=!0,s._c=!0,s._d=!0,s}function zn(e){const{type:t,vnode:n,proxy:s,withProxy:r,propsOptions:[o],slots:i,attrs:l,emit:a,render:u,renderCache:d,props:p,data:b,setupState:C,ctx:M,inheritAttrs:V}=e,ce=yn(e);let re,ae;try{if(n.shapeFlag&4){const y=r||s,O=y;re=He(u.call(O,y,d,p,C,b,M)),ae=l}else{const y=t;re=He(y.length>1?y(p,{attrs:l,slots:i,emit:a}):y(p,null)),ae=t.props?l:al(l)}}catch(y){Kt.length=0,On(y,e,1),re=j(Je)}let h=re;if(ae&&V!==!1){const y=Object.keys(ae),{shapeFlag:O}=h;y.length&&O&7&&(o&&y.some(us)&&(ae=cl(ae,o)),h=Et(h,ae,!1,!0))}return n.dirs&&(h=Et(h,null,!1,!0),h.dirs=h.dirs?h.dirs.concat(n.dirs):n.dirs),n.transition&&(h.transition=n.transition),re=h,yn(ce),re}const al=e=>{let t;for(const n in e)(n==="class"||n==="style"||Xt(n))&&((t||(t={}))[n]=e[n]);return t},cl=(e,t)=>{const n={};for(const s in e)(!us(s)||!(s.slice(9)in t))&&(n[s]=e[s]);return n};function ul(e,t,n){const{props:s,children:r,component:o}=e,{props:i,children:l,patchFlag:a}=t,u=o.emitsOptions;if(t.dirs||t.transition)return!0;if(n&&a>=0){if(a&1024)return!0;if(a&16)return s?Zs(s,i,u):!!i;if(a&8){const d=t.dynamicProps;for(let p=0;pe.__isSuspense;function co(e,t){t&&t.pendingBranch?N(e)?t.effects.push(...e):t.effects.push(e):ol(e)}const _l=Symbol.for("v-scx"),ml=()=>pt(_l);function uo(e,t){return $s(e,null,t)}const cn={};function We(e,t,n){return $s(e,t,n)}function $s(e,t,{immediate:n,deep:s,flush:r,once:o,onTrack:i,onTrigger:l}=ee){if(t&&o){const I=t;t=(...K)=>{I(...K),O()}}const a=ye,u=I=>s===!0?I:ft(I,s===!1?1:void 0);let d,p=!1,b=!1;if(we(e)?(d=()=>e.value,p=vn(e)):Ut(e)?(d=()=>u(e),p=!0):N(e)?(b=!0,p=e.some(I=>Ut(I)||vn(I)),d=()=>e.map(I=>{if(we(I))return I.value;if(Ut(I))return u(I);if(U(I))return Ge(I,a,2)})):U(e)?t?d=()=>Ge(e,a,2):d=()=>(C&&C(),Ne(e,a,3,[M])):d=Ee,t&&s){const I=d;d=()=>ft(I())}let C,M=I=>{C=h.onStop=()=>{Ge(I,a,4),C=h.onStop=void 0}},V;if(Fn)if(M=Ee,t?n&&Ne(t,a,3,[d(),b?[]:void 0,M]):d(),r==="sync"){const I=ml();V=I.__watcherHandles||(I.__watcherHandles=[])}else return Ee;let ce=b?new Array(e.length).fill(cn):cn;const re=()=>{if(!(!h.active||!h.dirty))if(t){const I=h.run();(s||p||(b?I.some((K,J)=>it(K,ce[J])):it(I,ce)))&&(C&&C(),Ne(t,a,3,[I,ce===cn?void 0:b&&ce[0]===cn?[]:ce,M]),ce=I)}else h.run()};re.allowRecurse=!!t;let ae;r==="sync"?ae=re:r==="post"?ae=()=>$e(re,a&&a.suspense):(re.pre=!0,a&&(re.id=a.uid),ae=()=>Cs(re));const h=new _s(d,Ee,ae),y=Ci(),O=()=>{h.stop(),y&&fs(y.effects,h)};return t?n?re():ce=h.run():r==="post"?$e(h.run.bind(h),a&&a.suspense):h.run(),V&&V.push(O),O}function gl(e,t,n){const s=this.proxy,r=le(e)?e.includes(".")?fo(s,e):()=>s[e]:e.bind(s,s);let o;U(t)?o=t:(o=t.handler,n=t);const i=en(this),l=$s(r,o.bind(s),n);return i(),l}function fo(e,t){const n=t.split(".");return()=>{let s=e;for(let r=0;r{ft(s,t,n)});else if(Hr(e))for(const s in e)ft(e[s],t,n);return e}function vl(e,t){if(pe===null)return e;const n=Un(pe)||pe.proxy,s=e.dirs||(e.dirs=[]);for(let r=0;r_e({name:e.name},t,{setup:e}))():e}const $t=e=>!!e.type.__asyncLoader,ho=e=>e.type.__isKeepAlive;function bl(e,t){po(e,"a",t)}function yl(e,t){po(e,"da",t)}function po(e,t,n=ye){const s=e.__wdc||(e.__wdc=()=>{let r=n;for(;r;){if(r.isDeactivated)return;r=r.parent}return e()});if(Dn(t,s,n),n){let r=n.parent;for(;r&&r.parent;)ho(r.parent.vnode)&&xl(s,t,n,r),r=r.parent}}function xl(e,t,n,s){const r=Dn(t,e,s,!0);Nn(()=>{fs(s[t],r)},n)}function Dn(e,t,n=ye,s=!1){if(n){const r=n[e]||(n[e]=[]),o=t.__weh||(t.__weh=(...i)=>{if(n.isUnmounted)return;Xe();const l=en(n),a=Ne(t,n,e,i);return l(),Ze(),a});return s?r.unshift(o):r.push(o),o}}const Qe=e=>(t,n=ye)=>(!Fn||e==="sp")&&Dn(e,(...s)=>t(...s),n),_o=Qe("bm"),bt=Qe("m"),wl=Qe("bu"),mo=Qe("u"),go=Qe("bum"),Nn=Qe("um"),kl=Qe("sp"),Cl=Qe("rtg"),Sl=Qe("rtc");function Tl(e,t=ye){Dn("ec",e,t)}function Zt(e,t,n,s){let r;const o=n&&n[s];if(N(e)||le(e)){r=new Array(e.length);for(let i=0,l=e.length;it(i,l,void 0,o&&o[l]));else{const i=Object.keys(e);r=new Array(i.length);for(let l=0,a=i.length;lkn(t)?!(t.type===Je||t.type===de&&!vo(t.children)):!0)?e:null}const rs=e=>e?Oo(e)?Un(e)||e.proxy:rs(e.parent):null,Bt=_e(Object.create(null),{$:e=>e,$el:e=>e.vnode.el,$data:e=>e.data,$props:e=>e.props,$attrs:e=>e.attrs,$slots:e=>e.slots,$refs:e=>e.refs,$parent:e=>rs(e.parent),$root:e=>rs(e.root),$emit:e=>e.emit,$options:e=>As(e),$forceUpdate:e=>e.f||(e.f=()=>{e.effect.dirty=!0,Cs(e.update)}),$nextTick:e=>e.n||(e.n=ro.bind(e.proxy)),$watch:e=>gl.bind(e)}),Yn=(e,t)=>e!==ee&&!e.__isScriptSetup&&Y(e,t),$l={get({_:e},t){if(t==="__v_skip")return!0;const{ctx:n,setupState:s,data:r,props:o,accessCache:i,type:l,appContext:a}=e;let u;if(t[0]!=="$"){const C=i[t];if(C!==void 0)switch(C){case 1:return s[t];case 2:return r[t];case 4:return n[t];case 3:return o[t]}else{if(Yn(s,t))return i[t]=1,s[t];if(r!==ee&&Y(r,t))return i[t]=2,r[t];if((u=e.propsOptions[0])&&Y(u,t))return i[t]=3,o[t];if(n!==ee&&Y(n,t))return i[t]=4,n[t];os&&(i[t]=0)}}const d=Bt[t];let p,b;if(d)return t==="$attrs"&&Ae(e.attrs,"get",""),d(e);if((p=l.__cssModules)&&(p=p[t]))return p;if(n!==ee&&Y(n,t))return i[t]=4,n[t];if(b=a.config.globalProperties,Y(b,t))return b[t]},set({_:e},t,n){const{data:s,setupState:r,ctx:o}=e;return Yn(r,t)?(r[t]=n,!0):s!==ee&&Y(s,t)?(s[t]=n,!0):Y(e.props,t)||t[0]==="$"&&t.slice(1)in e?!1:(o[t]=n,!0)},has({_:{data:e,setupState:t,accessCache:n,ctx:s,appContext:r,propsOptions:o}},i){let l;return!!n[i]||e!==ee&&Y(e,i)||Yn(t,i)||(l=o[0])&&Y(l,i)||Y(s,i)||Y(Bt,i)||Y(r.config.globalProperties,i)},defineProperty(e,t,n){return n.get!=null?e._.accessCache[t]=0:Y(n,"value")&&this.set(e,t,n.value,null),Reflect.defineProperty(e,t,n)}};function er(e){return N(e)?e.reduce((t,n)=>(t[n]=null,t),{}):e}let os=!0;function Al(e){const t=As(e),n=e.proxy,s=e.ctx;os=!1,t.beforeCreate&&tr(t.beforeCreate,e,"bc");const{data:r,computed:o,methods:i,watch:l,provide:a,inject:u,created:d,beforeMount:p,mounted:b,beforeUpdate:C,updated:M,activated:V,deactivated:ce,beforeDestroy:re,beforeUnmount:ae,destroyed:h,unmounted:y,render:O,renderTracked:I,renderTriggered:K,errorCaptured:J,serverPrefetch:Q,expose:B,inheritAttrs:oe,components:me,directives:fe,filters:Se}=t;if(u&&Il(u,s,null),i)for(const z in i){const E=i[z];U(E)&&(s[z]=E.bind(n))}if(r){const z=r.call(n,n);ne(z)&&(e.data=Rt(z))}if(os=!0,o)for(const z in o){const E=o[z],Fe=U(E)?E.bind(n,n):U(E.get)?E.get.bind(n,n):Ee,yt=!U(E)&&U(E.set)?E.set.bind(n):Ee,at=W({get:Fe,set:yt});Object.defineProperty(s,z,{enumerable:!0,configurable:!0,get:()=>at.value,set:Ue=>at.value=Ue})}if(l)for(const z in l)bo(l[z],s,n,z);if(a){const z=U(a)?a.call(n):a;Reflect.ownKeys(z).forEach(E=>{Ft(E,z[E])})}d&&tr(d,e,"c");function R(z,E){N(E)?E.forEach(Fe=>z(Fe.bind(n))):E&&z(E.bind(n))}if(R(_o,p),R(bt,b),R(wl,C),R(mo,M),R(bl,V),R(yl,ce),R(Tl,J),R(Sl,I),R(Cl,K),R(go,ae),R(Nn,y),R(kl,Q),N(B))if(B.length){const z=e.exposed||(e.exposed={});B.forEach(E=>{Object.defineProperty(z,E,{get:()=>n[E],set:Fe=>n[E]=Fe})})}else e.exposed||(e.exposed={});O&&e.render===Ee&&(e.render=O),oe!=null&&(e.inheritAttrs=oe),me&&(e.components=me),fe&&(e.directives=fe)}function Il(e,t,n=Ee){N(e)&&(e=is(e));for(const s in e){const r=e[s];let o;ne(r)?"default"in r?o=pt(r.from||s,r.default,!0):o=pt(r.from||s):o=pt(r),we(o)?Object.defineProperty(t,s,{enumerable:!0,configurable:!0,get:()=>o.value,set:i=>o.value=i}):t[s]=o}}function tr(e,t,n){Ne(N(e)?e.map(s=>s.bind(t.proxy)):e.bind(t.proxy),t,n)}function bo(e,t,n,s){const r=s.includes(".")?fo(n,s):()=>n[s];if(le(e)){const o=t[e];U(o)&&We(r,o)}else if(U(e))We(r,e.bind(n));else if(ne(e))if(N(e))e.forEach(o=>bo(o,t,n,s));else{const o=U(e.handler)?e.handler.bind(n):t[e.handler];U(o)&&We(r,o,e)}}function As(e){const t=e.type,{mixins:n,extends:s}=t,{mixins:r,optionsCache:o,config:{optionMergeStrategies:i}}=e.appContext,l=o.get(t);let a;return l?a=l:!r.length&&!n&&!s?a=t:(a={},r.length&&r.forEach(u=>xn(a,u,i,!0)),xn(a,t,i)),ne(t)&&o.set(t,a),a}function xn(e,t,n,s=!1){const{mixins:r,extends:o}=t;o&&xn(e,o,n,!0),r&&r.forEach(i=>xn(e,i,n,!0));for(const i in t)if(!(s&&i==="expose")){const l=El[i]||n&&n[i];e[i]=l?l(e[i],t[i]):t[i]}return e}const El={data:nr,props:sr,emits:sr,methods:Nt,computed:Nt,beforeCreate:ke,created:ke,beforeMount:ke,mounted:ke,beforeUpdate:ke,updated:ke,beforeDestroy:ke,beforeUnmount:ke,destroyed:ke,unmounted:ke,activated:ke,deactivated:ke,errorCaptured:ke,serverPrefetch:ke,components:Nt,directives:Nt,watch:Pl,provide:nr,inject:Ll};function nr(e,t){return t?e?function(){return _e(U(e)?e.call(this,this):e,U(t)?t.call(this,this):t)}:t:e}function Ll(e,t){return Nt(is(e),is(t))}function is(e){if(N(e)){const t={};for(let n=0;n1)return n&&U(t)?t.call(s&&s.proxy):t}}const xo={},wo=()=>Object.create(xo),ko=e=>Object.getPrototypeOf(e)===xo;function Hl(e,t,n,s=!1){const r={},o=wo();e.propsDefaults=Object.create(null),Co(e,t,r,o);for(const i in e.propsOptions[0])i in r||(r[i]=void 0);n?e.props=s?r:Ki(r):e.type.props?e.props=r:e.props=o,e.attrs=o}function Ml(e,t,n,s){const{props:r,attrs:o,vnode:{patchFlag:i}}=e,l=G(r),[a]=e.propsOptions;let u=!1;if((s||i>0)&&!(i&16)){if(i&8){const d=e.vnode.dynamicProps;for(let p=0;p{a=!0;const[b,C]=So(p,t,!0);_e(i,b),C&&l.push(...C)};!n&&t.mixins.length&&t.mixins.forEach(d),e.extends&&d(e.extends),e.mixins&&e.mixins.forEach(d)}if(!o&&!a)return ne(e)&&s.set(e,kt),kt;if(N(o))for(let d=0;d-1,C[1]=V<0||M-1||Y(C,"default"))&&l.push(p)}}}const u=[i,l];return ne(e)&&s.set(e,u),u}function rr(e){return e[0]!=="$"&&!St(e)}function or(e){return e===null?"null":typeof e=="function"?e.name||"":typeof e=="object"&&e.constructor&&e.constructor.name||""}function ir(e,t){return or(e)===or(t)}function lr(e,t){return N(t)?t.findIndex(n=>ir(n,e)):U(t)&&ir(t,e)?0:-1}const To=e=>e[0]==="_"||e==="$stable",Is=e=>N(e)?e.map(He):[He(e)],Dl=(e,t,n)=>{if(t._n)return t;const s=Pe((...r)=>Is(t(...r)),n);return s._c=!1,s},$o=(e,t,n)=>{const s=e._ctx;for(const r in e){if(To(r))continue;const o=e[r];if(U(o))t[r]=Dl(r,o,s);else if(o!=null){const i=Is(o);t[r]=()=>i}}},Ao=(e,t)=>{const n=Is(t);e.slots.default=()=>n},Nl=(e,t)=>{const n=e.slots=wo();if(e.vnode.shapeFlag&32){const s=t._;s?(_e(n,t),Mr(n,"_",s,!0)):$o(t,n)}else t&&Ao(e,t)},Fl=(e,t,n)=>{const{vnode:s,slots:r}=e;let o=!0,i=ee;if(s.shapeFlag&32){const l=t._;l?n&&l===1?o=!1:(_e(r,t),!n&&l===1&&delete r._):(o=!t.$stable,$o(t,r)),i=t}else t&&(Ao(e,t),i={default:1});if(o)for(const l in r)!To(l)&&i[l]==null&&delete r[l]};function wn(e,t,n,s,r=!1){if(N(e)){e.forEach((b,C)=>wn(b,t&&(N(t)?t[C]:t),n,s,r));return}if($t(s)&&!r)return;const o=s.shapeFlag&4?Un(s.component)||s.component.proxy:s.el,i=r?null:o,{i:l,r:a}=e,u=t&&t.r,d=l.refs===ee?l.refs={}:l.refs,p=l.setupState;if(u!=null&&u!==a&&(le(u)?(d[u]=null,Y(p,u)&&(p[u]=null)):we(u)&&(u.value=null)),U(a))Ge(a,l,12,[i,d]);else{const b=le(a),C=we(a);if(b||C){const M=()=>{if(e.f){const V=b?Y(p,a)?p[a]:d[a]:a.value;r?N(V)&&fs(V,o):N(V)?V.includes(o)||V.push(o):b?(d[a]=[o],Y(p,a)&&(p[a]=d[a])):(a.value=[o],e.k&&(d[e.k]=a.value))}else b?(d[a]=i,Y(p,a)&&(p[a]=i)):C&&(a.value=i,e.k&&(d[e.k]=i))};i?(M.id=-1,$e(M,n)):M()}}}let ze=!1;const Ul=e=>e.namespaceURI.includes("svg")&&e.tagName!=="foreignObject",jl=e=>e.namespaceURI.includes("MathML"),un=e=>{if(Ul(e))return"svg";if(jl(e))return"mathml"},Ht=e=>e.nodeType===8;function Bl(e){const{mt:t,p:n,o:{patchProp:s,createText:r,nextSibling:o,parentNode:i,remove:l,insert:a,createComment:u}}=e,d=(h,y)=>{if(!y.hasChildNodes()){__VUE_PROD_HYDRATION_MISMATCH_DETAILS__&&tt("Attempting to hydrate existing markup but container is empty. Performing full mount instead."),n(null,h,y),bn(),y._vnode=h;return}ze=!1,p(y.firstChild,h,null,null,null),bn(),y._vnode=h,ze&&console.error("Hydration completed but contains mismatches.")},p=(h,y,O,I,K,J=!1)=>{J=J||!!y.dynamicChildren;const Q=Ht(h)&&h.data==="[",B=()=>V(h,y,O,I,K,Q),{type:oe,ref:me,shapeFlag:fe,patchFlag:Se}=y;let Te=h.nodeType;y.el=h,Se===-2&&(J=!1,y.dynamicChildren=null);let R=null;switch(oe){case It:Te!==3?y.children===""?(a(y.el=r(""),i(h),h),R=h):R=B():(h.data!==y.children&&(ze=!0,__VUE_PROD_HYDRATION_MISMATCH_DETAILS__&&tt("Hydration text mismatch in",h.parentNode,` + - rendered on server: ${JSON.stringify(h.data)} + - expected on client: ${JSON.stringify(y.children)}`),h.data=y.children),R=o(h));break;case Je:ae(h)?(R=o(h),re(y.el=h.content.firstChild,h,O)):Te!==8||Q?R=B():R=o(h);break;case Wt:if(Q&&(h=o(h),Te=h.nodeType),Te===1||Te===3){R=h;const z=!y.children.length;for(let E=0;E{J=J||!!y.dynamicChildren;const{type:Q,props:B,patchFlag:oe,shapeFlag:me,dirs:fe,transition:Se}=y,Te=Q==="input"||Q==="option";if(Te||oe!==-1){fe&&Be(y,null,O,"created");let R=!1;if(ae(h)){R=Io(I,Se)&&O&&O.vnode.props&&O.vnode.props.appear;const E=h.content.firstChild;R&&Se.beforeEnter(E),re(E,h,O),y.el=h=E}if(me&16&&!(B&&(B.innerHTML||B.textContent))){let E=C(h.firstChild,y,h,O,I,K,J),Fe=!1;for(;E;){ze=!0,__VUE_PROD_HYDRATION_MISMATCH_DETAILS__&&!Fe&&(tt("Hydration children mismatch on",h,` +Server rendered element contains more child nodes than client vdom.`),Fe=!0);const yt=E;E=E.nextSibling,l(yt)}}else me&8&&h.textContent!==y.children&&(ze=!0,__VUE_PROD_HYDRATION_MISMATCH_DETAILS__&&tt("Hydration text content mismatch on",h,` + - rendered on server: ${h.textContent} + - expected on client: ${y.children}`),h.textContent=y.children);if(B)if(__VUE_PROD_HYDRATION_MISMATCH_DETAILS__||Te||!J||oe&48)for(const E in B)__VUE_PROD_HYDRATION_MISMATCH_DETAILS__&&Vl(h,E,B[E],y,O)&&(ze=!0),(Te&&(E.endsWith("value")||E==="indeterminate")||Xt(E)&&!St(E)||E[0]===".")&&s(h,E,null,B[E],void 0,void 0,O);else B.onClick&&s(h,"onClick",null,B.onClick,void 0,void 0,O);let z;(z=B&&B.onVnodeBeforeMount)&&Le(z,O,y),fe&&Be(y,null,O,"beforeMount"),((z=B&&B.onVnodeMounted)||fe||R)&&co(()=>{z&&Le(z,O,y),R&&Se.enter(h),fe&&Be(y,null,O,"mounted")},I)}return h.nextSibling},C=(h,y,O,I,K,J,Q)=>{Q=Q||!!y.dynamicChildren;const B=y.children,oe=B.length;let me=!1;for(let fe=0;fe{const{slotScopeIds:Q}=y;Q&&(K=K?K.concat(Q):Q);const B=i(h),oe=C(o(h),y,B,O,I,K,J);return oe&&Ht(oe)&&oe.data==="]"?o(y.anchor=oe):(ze=!0,a(y.anchor=u("]"),B,oe),oe)},V=(h,y,O,I,K,J)=>{if(ze=!0,__VUE_PROD_HYDRATION_MISMATCH_DETAILS__&&tt(`Hydration node mismatch: +- rendered on server:`,h,h.nodeType===3?"(text)":Ht(h)&&h.data==="["?"(start of fragment)":"",` +- expected on client:`,y.type),y.el=null,J){const oe=ce(h);for(;;){const me=o(h);if(me&&me!==oe)l(me);else break}}const Q=o(h),B=i(h);return l(h),n(null,y,B,Q,O,I,un(B),K),Q},ce=(h,y="[",O="]")=>{let I=0;for(;h;)if(h=o(h),h&&Ht(h)&&(h.data===y&&I++,h.data===O)){if(I===0)return o(h);I--}return h},re=(h,y,O)=>{const I=y.parentNode;I&&I.replaceChild(h,y);let K=O;for(;K;)K.vnode.el===y&&(K.vnode.el=K.subTree.el=h),K=K.parent},ae=h=>h.nodeType===1&&h.tagName.toLowerCase()==="template";return[d,p]}function Vl(e,t,n,s,r){var o;let i,l,a,u;if(t==="class")a=e.getAttribute("class"),u=Ce(n),Wl(ar(a||""),ar(u))||(i=l="class");else if(t==="style"){a=e.getAttribute("style"),u=le(n)?n:gi(Pn(n));const d=cr(a),p=cr(u);if(s.dirs)for(const{dir:C,value:M}of s.dirs)C.name==="show"&&!M&&p.set("display","none");const b=r==null?void 0:r.subTree;if(s===b||(b==null?void 0:b.type)===de&&b.children.includes(s)){const C=(o=r==null?void 0:r.getCssVars)==null?void 0:o.call(r);for(const M in C)p.set(`--${M}`,String(C[M]))}Kl(d,p)||(i=l="style")}else(e instanceof SVGElement&&yi(t)||e instanceof HTMLElement&&(Vs(t)||bi(t)))&&(Vs(t)?(a=e.hasAttribute(t),u=ps(n)):n==null?(a=e.hasAttribute(t),u=!1):(e.hasAttribute(t)?a=e.getAttribute(t):t==="value"&&e.tagName==="TEXTAREA"?a=e.value:a=!1,u=xi(n)?String(n):!1),a!==u&&(i="attribute",l=t));if(i){const d=C=>C===!1?"(not rendered)":`${l}="${C}"`,p=`Hydration ${i} mismatch on`,b=` + - rendered on server: ${d(a)} + - expected on client: ${d(u)} + Note: this mismatch is check-only. The DOM will not be rectified in production due to performance overhead. + You should fix the source of the mismatch.`;return tt(p,e,b),!0}return!1}function ar(e){return new Set(e.trim().split(/\s+/))}function Wl(e,t){if(e.size!==t.size)return!1;for(const n of e)if(!t.has(n))return!1;return!0}function cr(e){const t=new Map;for(const n of e.split(";")){let[s,r]=n.split(":");s=s==null?void 0:s.trim(),r=r==null?void 0:r.trim(),s&&r&&t.set(s,r)}return t}function Kl(e,t){if(e.size!==t.size)return!1;for(const[n,s]of e)if(s!==t.get(n))return!1;return!0}function ql(){typeof __VUE_PROD_HYDRATION_MISMATCH_DETAILS__!="boolean"&&(hs().__VUE_PROD_HYDRATION_MISMATCH_DETAILS__=!1)}const $e=co;function zl(e){return Yl(e,Bl)}function Yl(e,t){ql();const n=hs();n.__VUE__=!0;const{insert:s,remove:r,patchProp:o,createElement:i,createText:l,createComment:a,setText:u,setElementText:d,parentNode:p,nextSibling:b,setScopeId:C=Ee,insertStaticContent:M}=e,V=(c,f,_,m=null,g=null,w=null,S=void 0,x=null,k=!!f.dynamicChildren)=>{if(c===f)return;c&&!Mt(c,f)&&(m=nn(c),Ue(c,g,w,!0),c=null),f.patchFlag===-2&&(k=!1,f.dynamicChildren=null);const{type:v,ref:T,shapeFlag:P}=f;switch(v){case It:ce(c,f,_,m);break;case Je:re(c,f,_,m);break;case Wt:c==null&&ae(f,_,m,S);break;case de:me(c,f,_,m,g,w,S,x,k);break;default:P&1?O(c,f,_,m,g,w,S,x,k):P&6?fe(c,f,_,m,g,w,S,x,k):(P&64||P&128)&&v.process(c,f,_,m,g,w,S,x,k,xt)}T!=null&&g&&wn(T,c&&c.ref,w,f||c,!f)},ce=(c,f,_,m)=>{if(c==null)s(f.el=l(f.children),_,m);else{const g=f.el=c.el;f.children!==c.children&&u(g,f.children)}},re=(c,f,_,m)=>{c==null?s(f.el=a(f.children||""),_,m):f.el=c.el},ae=(c,f,_,m)=>{[c.el,c.anchor]=M(c.children,f,_,m,c.el,c.anchor)},h=({el:c,anchor:f},_,m)=>{let g;for(;c&&c!==f;)g=b(c),s(c,_,m),c=g;s(f,_,m)},y=({el:c,anchor:f})=>{let _;for(;c&&c!==f;)_=b(c),r(c),c=_;r(f)},O=(c,f,_,m,g,w,S,x,k)=>{f.type==="svg"?S="svg":f.type==="math"&&(S="mathml"),c==null?I(f,_,m,g,w,S,x,k):Q(c,f,g,w,S,x,k)},I=(c,f,_,m,g,w,S,x)=>{let k,v;const{props:T,shapeFlag:P,transition:L,dirs:F}=c;if(k=c.el=i(c.type,w,T&&T.is,T),P&8?d(k,c.children):P&16&&J(c.children,k,null,m,g,Gn(c,w),S,x),F&&Be(c,null,m,"created"),K(k,c,c.scopeId,S,m),T){for(const X in T)X!=="value"&&!St(X)&&o(k,X,null,T[X],w,c.children,m,g,qe);"value"in T&&o(k,"value",null,T.value,w),(v=T.onVnodeBeforeMount)&&Le(v,m,c)}F&&Be(c,null,m,"beforeMount");const q=Io(g,L);q&&L.beforeEnter(k),s(k,f,_),((v=T&&T.onVnodeMounted)||q||F)&&$e(()=>{v&&Le(v,m,c),q&&L.enter(k),F&&Be(c,null,m,"mounted")},g)},K=(c,f,_,m,g)=>{if(_&&C(c,_),m)for(let w=0;w{for(let v=k;v{const x=f.el=c.el;let{patchFlag:k,dynamicChildren:v,dirs:T}=f;k|=c.patchFlag&16;const P=c.props||ee,L=f.props||ee;let F;if(_&&ct(_,!1),(F=L.onVnodeBeforeUpdate)&&Le(F,_,f,c),T&&Be(f,c,_,"beforeUpdate"),_&&ct(_,!0),v?B(c.dynamicChildren,v,x,_,m,Gn(f,g),w):S||E(c,f,x,null,_,m,Gn(f,g),w,!1),k>0){if(k&16)oe(x,f,P,L,_,m,g);else if(k&2&&P.class!==L.class&&o(x,"class",null,L.class,g),k&4&&o(x,"style",P.style,L.style,g),k&8){const q=f.dynamicProps;for(let X=0;X{F&&Le(F,_,f,c),T&&Be(f,c,_,"updated")},m)},B=(c,f,_,m,g,w,S)=>{for(let x=0;x{if(_!==m){if(_!==ee)for(const x in _)!St(x)&&!(x in m)&&o(c,x,_[x],null,S,f.children,g,w,qe);for(const x in m){if(St(x))continue;const k=m[x],v=_[x];k!==v&&x!=="value"&&o(c,x,v,k,S,f.children,g,w,qe)}"value"in m&&o(c,"value",_.value,m.value,S)}},me=(c,f,_,m,g,w,S,x,k)=>{const v=f.el=c?c.el:l(""),T=f.anchor=c?c.anchor:l("");let{patchFlag:P,dynamicChildren:L,slotScopeIds:F}=f;F&&(x=x?x.concat(F):F),c==null?(s(v,_,m),s(T,_,m),J(f.children||[],_,T,g,w,S,x,k)):P>0&&P&64&&L&&c.dynamicChildren?(B(c.dynamicChildren,L,_,g,w,S,x),(f.key!=null||g&&f===g.subTree)&&Eo(c,f,!0)):E(c,f,_,T,g,w,S,x,k)},fe=(c,f,_,m,g,w,S,x,k)=>{f.slotScopeIds=x,c==null?f.shapeFlag&512?g.ctx.activate(f,_,m,S,k):Se(f,_,m,g,w,S,k):Te(c,f,k)},Se=(c,f,_,m,g,w,S)=>{const x=c.component=na(c,m,g);if(ho(c)&&(x.ctx.renderer=xt),sa(x),x.asyncDep){if(g&&g.registerDep(x,R),!c.el){const k=x.subTree=j(Je);re(null,k,f,_)}}else R(x,c,f,_,g,w,S)},Te=(c,f,_)=>{const m=f.component=c.component;if(ul(c,f,_))if(m.asyncDep&&!m.asyncResolved){z(m,f,_);return}else m.next=f,rl(m.update),m.effect.dirty=!0,m.update();else f.el=c.el,m.vnode=f},R=(c,f,_,m,g,w,S)=>{const x=()=>{if(c.isMounted){let{next:T,bu:P,u:L,parent:F,vnode:q}=c;{const wt=Lo(c);if(wt){T&&(T.el=q.el,z(c,T,S)),wt.asyncDep.then(()=>{c.isUnmounted||x()});return}}let X=T,te;ct(c,!1),T?(T.el=q.el,z(c,T,S)):T=q,P&&Kn(P),(te=T.props&&T.props.onVnodeBeforeUpdate)&&Le(te,F,T,q),ct(c,!0);const he=zn(c),Re=c.subTree;c.subTree=he,V(Re,he,p(Re.el),nn(Re),c,g,w),T.el=he.el,X===null&&fl(c,he.el),L&&$e(L,g),(te=T.props&&T.props.onVnodeUpdated)&&$e(()=>Le(te,F,T,q),g)}else{let T;const{el:P,props:L}=f,{bm:F,m:q,parent:X}=c,te=$t(f);if(ct(c,!1),F&&Kn(F),!te&&(T=L&&L.onVnodeBeforeMount)&&Le(T,X,f),ct(c,!0),P&&Vn){const he=()=>{c.subTree=zn(c),Vn(P,c.subTree,c,g,null)};te?f.type.__asyncLoader().then(()=>!c.isUnmounted&&he()):he()}else{const he=c.subTree=zn(c);V(null,he,_,m,c,g,w),f.el=he.el}if(q&&$e(q,g),!te&&(T=L&&L.onVnodeMounted)){const he=f;$e(()=>Le(T,X,he),g)}(f.shapeFlag&256||X&&$t(X.vnode)&&X.vnode.shapeFlag&256)&&c.a&&$e(c.a,g),c.isMounted=!0,f=_=m=null}},k=c.effect=new _s(x,Ee,()=>Cs(v),c.scope),v=c.update=()=>{k.dirty&&k.run()};v.id=c.uid,ct(c,!0),v()},z=(c,f,_)=>{f.component=c;const m=c.vnode.props;c.vnode=f,c.next=null,Ml(c,f.props,m,_),Fl(c,f.children,_),Xe(),Xs(c),Ze()},E=(c,f,_,m,g,w,S,x,k=!1)=>{const v=c&&c.children,T=c?c.shapeFlag:0,P=f.children,{patchFlag:L,shapeFlag:F}=f;if(L>0){if(L&128){yt(v,P,_,m,g,w,S,x,k);return}else if(L&256){Fe(v,P,_,m,g,w,S,x,k);return}}F&8?(T&16&&qe(v,g,w),P!==v&&d(_,P)):T&16?F&16?yt(v,P,_,m,g,w,S,x,k):qe(v,g,w,!0):(T&8&&d(_,""),F&16&&J(P,_,m,g,w,S,x,k))},Fe=(c,f,_,m,g,w,S,x,k)=>{c=c||kt,f=f||kt;const v=c.length,T=f.length,P=Math.min(v,T);let L;for(L=0;LT?qe(c,g,w,!0,!1,P):J(f,_,m,g,w,S,x,k,P)},yt=(c,f,_,m,g,w,S,x,k)=>{let v=0;const T=f.length;let P=c.length-1,L=T-1;for(;v<=P&&v<=L;){const F=c[v],q=f[v]=k?st(f[v]):He(f[v]);if(Mt(F,q))V(F,q,_,null,g,w,S,x,k);else break;v++}for(;v<=P&&v<=L;){const F=c[P],q=f[L]=k?st(f[L]):He(f[L]);if(Mt(F,q))V(F,q,_,null,g,w,S,x,k);else break;P--,L--}if(v>P){if(v<=L){const F=L+1,q=FL)for(;v<=P;)Ue(c[v],g,w,!0),v++;else{const F=v,q=v,X=new Map;for(v=q;v<=L;v++){const Ie=f[v]=k?st(f[v]):He(f[v]);Ie.key!=null&&X.set(Ie.key,v)}let te,he=0;const Re=L-q+1;let wt=!1,Ns=0;const Ot=new Array(Re);for(v=0;v=Re){Ue(Ie,g,w,!0);continue}let je;if(Ie.key!=null)je=X.get(Ie.key);else for(te=q;te<=L;te++)if(Ot[te-q]===0&&Mt(Ie,f[te])){je=te;break}je===void 0?Ue(Ie,g,w,!0):(Ot[je-q]=v+1,je>=Ns?Ns=je:wt=!0,V(Ie,f[je],_,null,g,w,S,x,k),he++)}const Fs=wt?Gl(Ot):kt;for(te=Fs.length-1,v=Re-1;v>=0;v--){const Ie=q+v,je=f[Ie],Us=Ie+1{const{el:w,type:S,transition:x,children:k,shapeFlag:v}=c;if(v&6){at(c.component.subTree,f,_,m);return}if(v&128){c.suspense.move(f,_,m);return}if(v&64){S.move(c,f,_,xt);return}if(S===de){s(w,f,_);for(let P=0;Px.enter(w),g);else{const{leave:P,delayLeave:L,afterLeave:F}=x,q=()=>s(w,f,_),X=()=>{P(w,()=>{q(),F&&F()})};L?L(w,q,X):X()}else s(w,f,_)},Ue=(c,f,_,m=!1,g=!1)=>{const{type:w,props:S,ref:x,children:k,dynamicChildren:v,shapeFlag:T,patchFlag:P,dirs:L}=c;if(x!=null&&wn(x,null,_,c,!0),T&256){f.ctx.deactivate(c);return}const F=T&1&&L,q=!$t(c);let X;if(q&&(X=S&&S.onVnodeBeforeUnmount)&&Le(X,f,c),T&6)si(c.component,_,m);else{if(T&128){c.suspense.unmount(_,m);return}F&&Be(c,null,f,"beforeUnmount"),T&64?c.type.remove(c,f,_,g,xt,m):v&&(w!==de||P>0&&P&64)?qe(v,f,_,!1,!0):(w===de&&P&384||!g&&T&16)&&qe(k,f,_),m&&Ms(c)}(q&&(X=S&&S.onVnodeUnmounted)||F)&&$e(()=>{X&&Le(X,f,c),F&&Be(c,null,f,"unmounted")},_)},Ms=c=>{const{type:f,el:_,anchor:m,transition:g}=c;if(f===de){ni(_,m);return}if(f===Wt){y(c);return}const w=()=>{r(_),g&&!g.persisted&&g.afterLeave&&g.afterLeave()};if(c.shapeFlag&1&&g&&!g.persisted){const{leave:S,delayLeave:x}=g,k=()=>S(_,w);x?x(c.el,w,k):k()}else w()},ni=(c,f)=>{let _;for(;c!==f;)_=b(c),r(c),c=_;r(f)},si=(c,f,_)=>{const{bum:m,scope:g,update:w,subTree:S,um:x}=c;m&&Kn(m),g.stop(),w&&(w.active=!1,Ue(S,c,f,_)),x&&$e(x,f),$e(()=>{c.isUnmounted=!0},f),f&&f.pendingBranch&&!f.isUnmounted&&c.asyncDep&&!c.asyncResolved&&c.suspenseId===f.pendingId&&(f.deps--,f.deps===0&&f.resolve())},qe=(c,f,_,m=!1,g=!1,w=0)=>{for(let S=w;Sc.shapeFlag&6?nn(c.component.subTree):c.shapeFlag&128?c.suspense.next():b(c.anchor||c.el);let jn=!1;const Ds=(c,f,_)=>{c==null?f._vnode&&Ue(f._vnode,null,null,!0):V(f._vnode||null,c,f,null,null,null,_),jn||(jn=!0,Xs(),bn(),jn=!1),f._vnode=c},xt={p:V,um:Ue,m:at,r:Ms,mt:Se,mc:J,pc:E,pbc:B,n:nn,o:e};let Bn,Vn;return t&&([Bn,Vn]=t(xt)),{render:Ds,hydrate:Bn,createApp:Ol(Ds,Bn)}}function Gn({type:e,props:t},n){return n==="svg"&&e==="foreignObject"||n==="mathml"&&e==="annotation-xml"&&t&&t.encoding&&t.encoding.includes("html")?void 0:n}function ct({effect:e,update:t},n){e.allowRecurse=t.allowRecurse=n}function Io(e,t){return(!e||e&&!e.pendingBranch)&&t&&!t.persisted}function Eo(e,t,n=!1){const s=e.children,r=t.children;if(N(s)&&N(r))for(let o=0;o>1,e[n[l]]0&&(t[s]=n[o-1]),n[o]=s)}}for(o=n.length,i=n[o-1];o-- >0;)n[o]=i,i=t[i];return n}function Lo(e){const t=e.subTree.component;if(t)return t.asyncDep&&!t.asyncResolved?t:Lo(t)}const Jl=e=>e.__isTeleport,de=Symbol.for("v-fgt"),It=Symbol.for("v-txt"),Je=Symbol.for("v-cmt"),Wt=Symbol.for("v-stc"),Kt=[];let Me=null;function A(e=!1){Kt.push(Me=e?null:[])}function Xl(){Kt.pop(),Me=Kt[Kt.length-1]||null}let Jt=1;function ur(e){Jt+=e}function Po(e){return e.dynamicChildren=Jt>0?Me||kt:null,Xl(),Jt>0&&Me&&Me.push(e),e}function H(e,t,n,s,r,o){return Po(D(e,t,n,s,r,o,!0))}function ve(e,t,n,s,r){return Po(j(e,t,n,s,r,!0))}function kn(e){return e?e.__v_isVNode===!0:!1}function Mt(e,t){return e.type===t.type&&e.key===t.key}const Ro=({key:e})=>e!=null?e:null,_n=({ref:e,ref_key:t,ref_for:n})=>(typeof e=="number"&&(e=""+e),e!=null?le(e)||we(e)||U(e)?{i:pe,r:e,k:t,f:!!n}:e:null);function D(e,t=null,n=null,s=0,r=null,o=e===de?0:1,i=!1,l=!1){const a={__v_isVNode:!0,__v_skip:!0,type:e,props:t,key:t&&Ro(t),ref:t&&_n(t),scopeId:Mn,slotScopeIds:null,children:n,component:null,suspense:null,ssContent:null,ssFallback:null,dirs:null,transition:null,el:null,anchor:null,target:null,targetAnchor:null,staticCount:0,shapeFlag:o,patchFlag:s,dynamicProps:r,dynamicChildren:null,appContext:null,ctx:pe};return l?(Es(a,n),o&128&&e.normalize(a)):n&&(a.shapeFlag|=le(n)?8:16),Jt>0&&!i&&Me&&(a.patchFlag>0||o&6)&&a.patchFlag!==32&&Me.push(a),a}const j=Zl;function Zl(e,t=null,n=null,s=0,r=null,o=!1){if((!e||e===dl)&&(e=Je),kn(e)){const l=Et(e,t,!0);return n&&Es(l,n),Jt>0&&!o&&Me&&(l.shapeFlag&6?Me[Me.indexOf(e)]=l:Me.push(l)),l.patchFlag|=-2,l}if(ca(e)&&(e=e.__vccOpts),t){t=Ql(t);let{class:l,style:a}=t;l&&!le(l)&&(t.class=Ce(l)),ne(a)&&(Xr(a)&&!N(a)&&(a=_e({},a)),t.style=Pn(a))}const i=le(e)?1:pl(e)?128:Jl(e)?64:ne(e)?4:U(e)?2:0;return D(e,t,n,s,r,i,o,!0)}function Ql(e){return e?Xr(e)||ko(e)?_e({},e):e:null}function Et(e,t,n=!1,s=!1){const{props:r,ref:o,patchFlag:i,children:l,transition:a}=e,u=t?Ls(r||{},t):r,d={__v_isVNode:!0,__v_skip:!0,type:e.type,props:u,key:u&&Ro(u),ref:t&&t.ref?n&&o?N(o)?o.concat(_n(t)):[o,_n(t)]:_n(t):o,scopeId:e.scopeId,slotScopeIds:e.slotScopeIds,children:l,target:e.target,targetAnchor:e.targetAnchor,staticCount:e.staticCount,shapeFlag:e.shapeFlag,patchFlag:t&&e.type!==de?i===-1?16:i|16:i,dynamicProps:e.dynamicProps,dynamicChildren:e.dynamicChildren,appContext:e.appContext,dirs:e.dirs,transition:a,component:e.component,suspense:e.suspense,ssContent:e.ssContent&&Et(e.ssContent),ssFallback:e.ssFallback&&Et(e.ssFallback),el:e.el,anchor:e.anchor,ctx:e.ctx,ce:e.ce};return a&&s&&(d.transition=a.clone(d)),d}function Qt(e=" ",t=0){return j(It,null,e,t)}function nd(e,t){const n=j(Wt,null,e);return n.staticCount=t,n}function Z(e="",t=!1){return t?(A(),ve(Je,null,e)):j(Je,null,e)}function He(e){return e==null||typeof e=="boolean"?j(Je):N(e)?j(de,null,e.slice()):typeof e=="object"?st(e):j(It,null,String(e))}function st(e){return e.el===null&&e.patchFlag!==-1||e.memo?e:Et(e)}function Es(e,t){let n=0;const{shapeFlag:s}=e;if(t==null)t=null;else if(N(t))n=16;else if(typeof t=="object")if(s&65){const r=t.default;r&&(r._c&&(r._d=!1),Es(e,r()),r._c&&(r._d=!0));return}else{n=32;const r=t._;!r&&!ko(t)?t._ctx=pe:r===3&&pe&&(pe.slots._===1?t._=1:(t._=2,e.patchFlag|=1024))}else U(t)?(t={default:t,_ctx:pe},n=32):(t=String(t),s&64?(n=16,t=[Qt(t)]):n=8);e.children=t,e.shapeFlag|=n}function Ls(...e){const t={};for(let n=0;n{let r;return(r=e[n])||(r=e[n]=[]),r.push(s),o=>{r.length>1?r.forEach(i=>i(o)):r[0](o)}};Cn=t("__VUE_INSTANCE_SETTERS__",n=>ye=n),as=t("__VUE_SSR_SETTERS__",n=>Fn=n)}const en=e=>{const t=ye;return Cn(e),e.scope.on(),()=>{e.scope.off(),Cn(t)}},fr=()=>{ye&&ye.scope.off(),Cn(null)};function Oo(e){return e.vnode.shapeFlag&4}let Fn=!1;function sa(e,t=!1){t&&as(t);const{props:n,children:s}=e.vnode,r=Oo(e);Hl(e,n,r,t),Nl(e,s);const o=r?ra(e,t):void 0;return t&&as(!1),o}function ra(e,t){const n=e.type;e.accessCache=Object.create(null),e.proxy=new Proxy(e.ctx,$l);const{setup:s}=n;if(s){const r=e.setupContext=s.length>1?ia(e):null,o=en(e);Xe();const i=Ge(s,e,0,[e.props,r]);if(Ze(),o(),Rr(i)){if(i.then(fr,fr),t)return i.then(l=>{dr(e,l,t)}).catch(l=>{On(l,e,0)});e.asyncDep=i}else dr(e,i,t)}else Ho(e,t)}function dr(e,t,n){U(t)?e.type.__ssrInlineRender?e.ssrRender=t:e.render=t:ne(t)&&(e.setupState=to(t)),Ho(e,n)}let hr;function Ho(e,t,n){const s=e.type;if(!e.render){if(!t&&hr&&!s.render){const r=s.template||As(e).template;if(r){const{isCustomElement:o,compilerOptions:i}=e.appContext.config,{delimiters:l,compilerOptions:a}=s,u=_e(_e({isCustomElement:o,delimiters:l},i),a);s.render=hr(r,u)}}e.render=s.render||Ee}{const r=en(e);Xe();try{Al(e)}finally{Ze(),r()}}}const oa={get(e,t){return Ae(e,"get",""),e[t]}};function ia(e){const t=n=>{e.exposed=n||{}};return{attrs:new Proxy(e.attrs,oa),slots:e.slots,emit:e.emit,expose:t}}function Un(e){if(e.exposed)return e.exposeProxy||(e.exposeProxy=new Proxy(to(hn(e.exposed)),{get(t,n){if(n in t)return t[n];if(n in Bt)return Bt[n](e)},has(t,n){return n in t||n in Bt}}))}const la=/(?:^|[-_])(\w)/g,aa=e=>e.replace(la,t=>t.toUpperCase()).replace(/[-_]/g,"");function Mo(e,t=!0){return U(e)?e.displayName||e.name:e.name||t&&e.__name}function Do(e,t,n=!1){let s=Mo(t);if(!s&&t.__file){const r=t.__file.match(/([^/\\]+)\.\w+$/);r&&(s=r[1])}if(!s&&e&&e.parent){const r=o=>{for(const i in o)if(o[i]===t)return i};s=r(e.components||e.parent.type.components)||r(e.appContext.components)}return s?aa(s):n?"App":"Anonymous"}function ca(e){return U(e)&&"__vccOpts"in e}const W=(e,t)=>qi(e,t,Fn);function mt(e,t,n){const s=arguments.length;return s===2?ne(t)&&!N(t)?kn(t)?j(e,null,[t]):j(e,t):j(e,null,t):(s>3?n=Array.prototype.slice.call(arguments,2):s===3&&kn(n)&&(n=[n]),j(e,t,n))}const ua="3.4.26";/** +* @vue/runtime-dom v3.4.26 +* (c) 2018-present Yuxi (Evan) You and Vue contributors +* @license MIT +**/const fa="http://www.w3.org/2000/svg",da="http://www.w3.org/1998/Math/MathML",rt=typeof document!="undefined"?document:null,pr=rt&&rt.createElement("template"),ha={insert:(e,t,n)=>{t.insertBefore(e,n||null)},remove:e=>{const t=e.parentNode;t&&t.removeChild(e)},createElement:(e,t,n,s)=>{const r=t==="svg"?rt.createElementNS(fa,e):t==="mathml"?rt.createElementNS(da,e):rt.createElement(e,n?{is:n}:void 0);return e==="select"&&s&&s.multiple!=null&&r.setAttribute("multiple",s.multiple),r},createText:e=>rt.createTextNode(e),createComment:e=>rt.createComment(e),setText:(e,t)=>{e.nodeValue=t},setElementText:(e,t)=>{e.textContent=t},parentNode:e=>e.parentNode,nextSibling:e=>e.nextSibling,querySelector:e=>rt.querySelector(e),setScopeId(e,t){e.setAttribute(t,"")},insertStaticContent(e,t,n,s,r,o){const i=n?n.previousSibling:t.lastChild;if(r&&(r===o||r.nextSibling))for(;t.insertBefore(r.cloneNode(!0),n),!(r===o||!(r=r.nextSibling)););else{pr.innerHTML=s==="svg"?`${e}`:s==="mathml"?`${e}`:e;const l=pr.content;if(s==="svg"||s==="mathml"){const a=l.firstChild;for(;a.firstChild;)l.appendChild(a.firstChild);l.removeChild(a)}t.insertBefore(l,n)}return[i?i.nextSibling:t.firstChild,n?n.previousSibling:t.lastChild]}},pa=Symbol("_vtc");function _a(e,t,n){const s=e[pa];s&&(t=(t?[t,...s]:[...s]).join(" ")),t==null?e.removeAttribute("class"):n?e.setAttribute("class",t):e.className=t}const Sn=Symbol("_vod"),No=Symbol("_vsh"),ma={beforeMount(e,{value:t},{transition:n}){e[Sn]=e.style.display==="none"?"":e.style.display,n&&t?n.beforeEnter(e):Dt(e,t)},mounted(e,{value:t},{transition:n}){n&&t&&n.enter(e)},updated(e,{value:t,oldValue:n},{transition:s}){!t!=!n&&(s?t?(s.beforeEnter(e),Dt(e,!0),s.enter(e)):s.leave(e,()=>{Dt(e,!1)}):Dt(e,t))},beforeUnmount(e,{value:t}){Dt(e,t)}};function Dt(e,t){e.style.display=t?e[Sn]:"none",e[No]=!t}const ga=Symbol(""),va=/(^|;)\s*display\s*:/;function ba(e,t,n){const s=e.style,r=le(n);let o=!1;if(n&&!r){if(t)if(le(t))for(const i of t.split(";")){const l=i.slice(0,i.indexOf(":")).trim();n[l]==null&&mn(s,l,"")}else for(const i in t)n[i]==null&&mn(s,i,"");for(const i in n)i==="display"&&(o=!0),mn(s,i,n[i])}else if(r){if(t!==n){const i=s[ga];i&&(n+=";"+i),s.cssText=n,o=va.test(n)}}else t&&e.removeAttribute("style");Sn in e&&(e[Sn]=o?s.display:"",e[No]&&(s.display="none"))}const _r=/\s*!important$/;function mn(e,t,n){if(N(n))n.forEach(s=>mn(e,t,s));else if(n==null&&(n=""),t.startsWith("--"))e.setProperty(t,n);else{const s=ya(e,t);_r.test(n)?e.setProperty(vt(s),n.replace(_r,""),"important"):e[s]=n}}const mr=["Webkit","Moz","ms"],Jn={};function ya(e,t){const n=Jn[t];if(n)return n;let s=Ke(t);if(s!=="filter"&&s in e)return Jn[t]=s;s=Ln(s);for(let r=0;rXn||($a.then(()=>Xn=0),Xn=Date.now());function Ia(e,t){const n=s=>{if(!s._vts)s._vts=Date.now();else if(s._vts<=n.attached)return;Ne(Ea(s,n.value),t,5,[s])};return n.value=e,n.attached=Aa(),n}function Ea(e,t){if(N(t)){const n=e.stopImmediatePropagation;return e.stopImmediatePropagation=()=>{n.call(e),e._stopped=!0},t.map(s=>r=>!r._stopped&&s&&s(r))}else return t}const yr=e=>e.charCodeAt(0)===111&&e.charCodeAt(1)===110&&e.charCodeAt(2)>96&&e.charCodeAt(2)<123,La=(e,t,n,s,r,o,i,l,a)=>{const u=r==="svg";t==="class"?_a(e,s,u):t==="style"?ba(e,n,s):Xt(t)?us(t)||Sa(e,t,n,s,i):(t[0]==="."?(t=t.slice(1),!0):t[0]==="^"?(t=t.slice(1),!1):Pa(e,t,s,u))?wa(e,t,s,o,i,l,a):(t==="true-value"?e._trueValue=s:t==="false-value"&&(e._falseValue=s),xa(e,t,s,u))};function Pa(e,t,n,s){if(s)return!!(t==="innerHTML"||t==="textContent"||t in e&&yr(t)&&U(n));if(t==="spellcheck"||t==="draggable"||t==="translate"||t==="form"||t==="list"&&e.tagName==="INPUT"||t==="type"&&e.tagName==="TEXTAREA")return!1;if(t==="width"||t==="height"){const r=e.tagName;if(r==="IMG"||r==="VIDEO"||r==="CANVAS"||r==="SOURCE")return!1}return yr(t)&&le(n)?!1:t in e}const Ra=_e({patchProp:La},ha);let Zn,xr=!1;function Oa(){return Zn=xr?Zn:zl(Ra),xr=!0,Zn}const Ha=(...e)=>{const t=Oa().createApp(...e),{mount:n}=t;return t.mount=s=>{const r=Da(s);if(r)return n(r,!0,Ma(r))},t};function Ma(e){if(e instanceof SVGElement)return"svg";if(typeof MathMLElement=="function"&&e instanceof MathMLElement)return"mathml"}function Da(e){return le(e)?document.querySelector(e):e}var Na='{"lang":"en-US","title":"Swagger-PHP","description":"Generate OpenAPI documentation for your RESTful API.","base":"/swagger-php/","head":[],"themeConfig":{"repo":"zircote/swagger-php","docsDir":"docs","docsBranch":"master","editLinks":false,"editLinkText":"Edit this page on GitHub","nav":[{"text":"User Guide","link":"/guide/"},{"text":"Reference","link":"/reference/"},{"text":"OpenApi","link":"https://learn.openapis.org/"},{"text":"Releases","link":"https://github.com/zircote/swagger-php/releases"}],"sidebar":{"/guide/":[{"text":"Introduction","children":[{"text":"What is Swagger-PHP?","link":"/guide/"},{"text":"Installation","link":"/guide/installation"},{"text":"Generating OpenAPI documents","link":"/guide/generating-openapi-documents"}]},{"text":"Annotating your code","children":[{"text":"Attributes","link":"/guide/attributes"},{"text":"Annotations","link":"/guide/annotations"},{"text":"Required elements","link":"/guide/required-elements"},{"text":"Common techniques","link":"/guide/common-techniques"}]},{"text":"Upgrading","children":[{"text":"Migration from 3.x to 4.x","link":"/guide/migrating-to-v4"},{"text":"Migration from 2.x to 3.x","link":"/guide/migrating-to-v3"}]},{"text":"Other","children":[{"text":"Cookbook","link":"/guide/cookbook"},{"text":"FAQ","link":"/guide/faq"},{"text":"Under the hood","link":"/guide/under-the-hood"},{"text":"Related Projects","link":"/related-projects"}]}],"/reference/":[{"text":"Reference","children":[{"text":"Attributes","link":"/reference/attributes"},{"text":"Annotations","link":"/reference/annotations"}]},{"text":"Api","children":[{"text":"Generator","link":"/reference/generator"},{"text":"Processors","link":"/reference/processors"}]}]}},"locales":{},"langs":{},"scrollOffset":90}';const Fo=/^https?:/i,De=typeof window!="undefined";function Fa(e,t){t.sort((n,s)=>{const r=s.split("/").length-n.split("/").length;return r!==0?r:s.length-n.length});for(const n of t)if(e.startsWith(n))return n}function wr(e,t){const n=Fa(t,Object.keys(e));return n?e[n]:void 0}function Ua(e){const{locales:t}=e.themeConfig||{},n=e.locales;return t&&n?Object.keys(t).reduce((s,r)=>(s[r]={label:t[r].label,lang:n[r].lang},s),{}):{}}function ja(e,t){t=Ba(e,t);const n=wr(e.locales||{},t),s=wr(e.themeConfig.locales||{},t);return Object.assign({},e,n,{themeConfig:Object.assign({},e.themeConfig,s,{locales:{}}),lang:(n||e).lang,locales:{},langs:Ua(e)})}function Ba(e,t){if(!De)return t;const n=e.base,s=n.endsWith("/")?n.slice(0,-1):n;return t.slice(s.length)}const Uo=Symbol(),tn=zi(Va(Na));function Va(e){return JSON.parse(e)}function Wa(e){const t=W(()=>ja(tn.value,e.path));return{site:t,theme:W(()=>t.value.themeConfig),page:W(()=>e.data),frontmatter:W(()=>e.data.frontmatter),lang:W(()=>t.value.lang),localePath:W(()=>{const{langs:n,lang:s}=t.value,r=Object.keys(n).find(o=>n[o].lang===s);return Lt(r||"/")}),title:W(()=>e.data.title?e.data.title+" | "+t.value.title:t.value.title),description:W(()=>e.data.description||t.value.description)}}function ge(){const e=pt(Uo);if(!e)throw new Error("vitepress data not properly injected in app");return e}function Ka(e,t){return`${e}${t}`.replace(/\/+/g,"/")}function Lt(e){return Fo.test(e)?e:Ka(tn.value.base,e)}function jo(e){let t=e.replace(/\.html$/,"");if(t=decodeURIComponent(t),t.endsWith("/")&&(t+="index"),De){const n="/swagger-php/";t=t.slice(n.length).replace(/\//g,"_")+".md";const s=__VP_HASH_MAP__[t.toLowerCase()];t=`${n}assets/${t}.${s}.js`}else t=`./${t.slice(1).replace(/\//g,"_")}.md.js`;return t}const Bo=Symbol(),kr="http://a.com",Vo={relativePath:"",title:"404",description:"Not Found",headers:[],frontmatter:{},lastUpdated:0},qa=()=>({path:"/",component:null,data:Vo});function za(e,t){const n=Rt(qa());function s(i=De?location.href:"/"){const l=new URL(i,kr);return!l.pathname.endsWith("/")&&!l.pathname.endsWith(".html")&&(l.pathname+=".html",i=l.pathname+l.search+l.hash),De&&(history.replaceState({scrollPosition:window.scrollY},document.title),history.pushState(null,"",i)),o(i)}let r=null;async function o(i,l=0,a=!1){const u=new URL(i,kr),d=r=u.pathname;try{let p=e(d);if("then"in p&&typeof p.then=="function"&&(p=await p),r===d){r=null;const{default:b,__pageData:C}=p;if(!b)throw new Error(`Invalid route component: ${b}`);n.path=d,n.component=hn(b),n.data=hn(JSON.parse(C)),De&&ro(()=>{if(u.hash&&!l){let M=null;try{M=document.querySelector(decodeURIComponent(u.hash))}catch(V){console.warn(V)}if(M){Cr(M,u.hash);return}}window.scrollTo(0,l)})}}catch(p){if(p.message.match(/fetch/)||console.error(p),!a)try{const b=await fetch(tn.value.base+"hashmap.json");window.__VP_HASH_MAP__=await b.json(),await o(i,l,!0);return}catch{}r===d&&(r=null,n.path=d,n.component=t?hn(t):null,n.data=Vo)}}return De&&(window.addEventListener("click",i=>{const l=i.target.closest("a");if(l){const{href:a,protocol:u,hostname:d,pathname:p,hash:b,target:C}=l,M=window.location,V=p.match(/\.\w+$/);!i.ctrlKey&&!i.shiftKey&&!i.altKey&&!i.metaKey&&C!=="_blank"&&u===M.protocol&&d===M.hostname&&!(V&&V[0]!==".html")&&(i.preventDefault(),p===M.pathname?b&&b!==M.hash&&(history.pushState(null,"",b),window.dispatchEvent(new Event("hashchange")),Cr(l,b,l.classList.contains("header-anchor"))):s(a))}},{capture:!0}),window.addEventListener("popstate",i=>{o(location.href,i.state&&i.state.scrollPosition||0)}),window.addEventListener("hashchange",i=>{i.preventDefault()})),{route:n,go:s}}function Ya(){const e=pt(Bo);if(!e)throw new Error("useRouter() is called without provider.");return e}function lt(){return Ya().route}function Cr(e,t,n=!1){let s=null;try{s=e.classList.contains("header-anchor")?e:document.querySelector(decodeURIComponent(t))}catch(r){console.warn(r)}if(s){let r=tn.value.scrollOffset;typeof r=="string"&&(r=document.querySelector(r).getBoundingClientRect().bottom+24);const o=parseInt(window.getComputedStyle(s).paddingTop,10),i=window.scrollY+s.getBoundingClientRect().top-r+o;!n||Math.abs(i-window.scrollY)>window.innerHeight?window.scrollTo(0,i):window.scrollTo({left:0,top:i,behavior:"smooth"})}}function Ga(e,t){let n=[],s=!0;const r=o=>{if(s){s=!1;return}const i=[],l=Math.min(n.length,o.length);for(let a=0;adocument.head.removeChild(a)),o.slice(l).forEach(a=>{const u=Sr(a);document.head.appendChild(u),i.push(u)}),n=i};uo(()=>{const o=e.data,i=t.value,l=o&&o.title,a=o&&o.description,u=o&&o.frontmatter.head;document.title=(l?l+" | ":"")+i.title,document.querySelector("meta[name=description]").setAttribute("content",a||i.description),r([...u?Xa(u):[]])})}function Sr([e,t,n]){const s=document.createElement(e);for(const r in t)s.setAttribute(r,t[r]);return n&&(s.innerHTML=n),s}function Ja(e){return e[0]==="meta"&&e[1]&&e[1].name==="description"}function Xa(e){return e.filter(t=>!Ja(t))}const Za=se({name:"VitePressContent",setup(){const e=lt();return()=>mt("div",{style:{position:"relative"}},[e.component?mt(e.component):null])}});var ue=(e,t)=>{const n=e.__vccOpts||e;for(const[s,r]of t)n[s]=r;return n};const Qa=e=>(Ss("data-v-765646fb"),e=e(),Ts(),e),ec=Qa(()=>D("p",{class:"title"},"Debug",-1)),tc={class:"block"};se({__name:"Debug",setup(e){const t=ge(),n=_t(null),s=_t(!1),r=Rt(t);return We(s,o=>{o||(n.value.scrollTop=0)}),(o,i)=>(A(),H("div",{class:Ce(["debug",{open:s.value}]),ref_key:"el",ref:n,onClick:i[0]||(i[0]=l=>s.value=!s.value)},[ec,D("pre",tc,xe(r),1)],2))}});const nc=/#.*$/,sc=/(index)?\.(md|html)$/,Tn=/\/$/,rc=/^[a-z]+:/i;function Ps(e){return Array.isArray(e)}function Rs(e){return rc.test(e)}function oc(e,t){if(t===void 0)return!1;const n=Tr(`/${e.data.relativePath}`),s=Tr(t);return n===s}function Tr(e){return decodeURI(e).replace(nc,"").replace(sc,"")}function ic(e,t){const n=e.endsWith("/"),s=t.startsWith("/");return n&&s?e.slice(0,-1)+t:!n&&!s?`${e}/${t}`:e+t}function cs(e){return/^\//.test(e)?e:`/${e}`}function Wo(e){return e.replace(/(index)?(\.(md|html))?$/,"")||"/"}function lc(e){return e===!1||e==="auto"||Ps(e)}function ac(e){return e.children!==void 0}function cc(e){return Ps(e)?e.length===0:!e}function Os(e,t){if(lc(e))return e;t=cs(t);for(const n in e)if(t.startsWith(cs(n)))return e[n];return"auto"}function Ko(e){return e.reduce((t,n)=>(n.link&&t.push({text:n.text,link:Wo(n.link)}),ac(n)&&(t=[...t,...Ko(n.children)]),t),[])}function qo(e){const t=lt(),n=Rs(e.value.link);return{props:W(()=>{const r=$r(`/${t.data.relativePath}`);let o=!1;if(e.value.activeMatch)o=new RegExp(e.value.activeMatch).test(r);else{const i=$r(e.value.link);o=i==="/"?i===r:r.startsWith(i)}return{class:{active:o,isExternal:n},href:n?e.value.link:Lt(e.value.link),target:e.value.target||(n?"_blank":null),rel:e.value.rel||(n?"noopener noreferrer":null),"aria-label":e.value.ariaLabel}}),isExternal:n}}function $r(e){return e.replace(/#.*$/,"").replace(/\?.*$/,"").replace(/\.(html|md)$/,"").replace(/\/index$/,"/")}const uc={},fc={class:"icon outbound",xmlns:"http://www.w3.org/2000/svg","aria-hidden":"true",x:"0px",y:"0px",viewBox:"0 0 100 100",width:"15",height:"15"},dc=D("path",{fill:"currentColor",d:"M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"},null,-1),hc=D("polygon",{fill:"currentColor",points:"45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"},null,-1),pc=[dc,hc];function _c(e,t){return A(),H("svg",fc,pc)}var Hs=ue(uc,[["render",_c]]);const mc={class:"nav-link"},gc=se({__name:"NavLink",props:{item:{}},setup(e){const n=ws(e),{props:s,isExternal:r}=qo(n.item);return(o,i)=>(A(),H("div",mc,[D("a",Ls({class:"item"},$(s)),[Qt(xe(o.item.text)+" ",1),$(r)?(A(),ve(Hs,{key:0})):Z("",!0)],16)]))}});var $n=ue(gc,[["__scopeId","data-v-49fe041d"]]);const vc={key:0,class:"home-hero"},bc={key:0,class:"figure"},yc=["src","alt"],xc={key:1,id:"main-title",class:"title"},wc={key:2,class:"tagline"},kc=se({__name:"HomeHero",setup(e){const{site:t,frontmatter:n}=ge(),s=W(()=>{const{heroImage:i,heroText:l,tagline:a,actionLink:u,actionText:d}=n.value;return i||l||a||u&&d}),r=W(()=>n.value.heroText||t.value.title),o=W(()=>n.value.tagline||t.value.description);return(i,l)=>s.value?(A(),H("header",vc,[$(n).heroImage?(A(),H("figure",bc,[D("img",{class:"image",src:$(Lt)($(n).heroImage),alt:$(n).heroAlt},null,8,yc)])):Z("",!0),r.value?(A(),H("h1",xc,xe(r.value),1)):Z("",!0),o.value?(A(),H("p",wc,xe(o.value),1)):Z("",!0),$(n).actionLink&&$(n).actionText?(A(),ve($n,{key:3,item:{link:$(n).actionLink,text:$(n).actionText},class:"action"},null,8,["item"])):Z("",!0),$(n).altActionLink&&$(n).altActionText?(A(),ve($n,{key:4,item:{link:$(n).altActionLink,text:$(n).altActionText},class:"action alt"},null,8,["item"])):Z("",!0)])):Z("",!0)}});var Cc=ue(kc,[["__scopeId","data-v-5d8b683d"]]);const Sc={key:0,class:"home-features"},Tc={class:"wrapper"},$c={class:"container"},Ac={class:"features"},Ic={key:0,class:"title"},Ec={key:1,class:"details"},Lc=se({__name:"HomeFeatures",setup(e){const{frontmatter:t}=ge(),n=W(()=>t.value.features&&t.value.features.length>0),s=W(()=>t.value.features?t.value.features:[]);return(r,o)=>n.value?(A(),H("div",Sc,[D("div",Tc,[D("div",$c,[D("div",Ac,[(A(!0),H(de,null,Zt(s.value,(i,l)=>(A(),H("section",{key:l,class:"feature"},[i.title?(A(),H("h2",Ic,xe(i.title),1)):Z("",!0),i.details?(A(),H("p",Ec,xe(i.details),1)):Z("",!0)]))),128))])])])])):Z("",!0)}});var Pc=ue(Lc,[["__scopeId","data-v-245bde66"]]);const Rc={key:0,class:"footer"},Oc={class:"container"},Hc={class:"text"},Mc=se({__name:"HomeFooter",setup(e){const{frontmatter:t}=ge();return(n,s)=>$(t).footer?(A(),H("footer",Rc,[D("div",Oc,[D("p",Hc,xe($(t).footer),1)])])):Z("",!0)}});var Dc=ue(Mc,[["__scopeId","data-v-bff49316"]]);const Nc={class:"home","aria-labelledby":"main-title"},Fc={class:"home-content"},Uc=se({__name:"Home",setup(e){return(t,n)=>{const s=At("Content");return A(),H("main",Nc,[j(Cc),ie(t.$slots,"hero",{},void 0,!0),j(Pc),D("div",Fc,[j(s)]),ie(t.$slots,"features",{},void 0,!0),j(Dc),ie(t.$slots,"footer",{},void 0,!0)])}}});var jc=ue(Uc,[["__scopeId","data-v-8382b818"]]);const Bc=["href","aria-label"],Vc=["src"],Wc=se({__name:"NavBarTitle",setup(e){const{site:t,theme:n,localePath:s}=ge();return(r,o)=>(A(),H("a",{class:"nav-bar-title",href:$(s),"aria-label":`${$(t).title}, back to home`},[$(n).logo?(A(),H("img",{key:0,class:"logo",src:$(Lt)($(n).logo),alt:"Logo"},null,8,Vc)):Z("",!0),Qt(" "+xe($(t).title),1)],8,Bc))}});var Kc=ue(Wc,[["__scopeId","data-v-016a8bd8"]]);function qc(){const{site:e,localePath:t,theme:n}=ge();return W(()=>{const s=e.value.langs,r=Object.keys(s);if(r.length<2)return null;const i=lt().path.replace(t.value,""),l=r.map(u=>({text:s[u].label,link:`${u}${i}`}));return{text:n.value.selectText||"Languages",items:l}})}const zc=["GitHub","GitLab","Bitbucket"].map(e=>[e,new RegExp(e,"i")]);function Yc(){const{site:e}=ge();return W(()=>{const t=e.value.themeConfig,n=t.docsRepo||t.repo;if(!n)return null;const s=Gc(n);return{text:Jc(s,t.repoLabel),link:s}})}function Gc(e){return Fo.test(e)?e:`https://github.com/${e}`}function Jc(e,t){if(t)return t;const n=e.match(/^https?:\/\/[^/]+/);if(!n)return"Source";const s=zc.find(([r,o])=>o.test(n[0]));return s&&s[0]?s[0]:"Source"}const Xc=e=>(Ss("data-v-07381bdb"),e=e(),Ts(),e),Zc={class:"nav-dropdown-link-item"},Qc=Xc(()=>D("span",{class:"arrow"},null,-1)),eu={class:"text"},tu={class:"icon"},nu=se({__name:"NavDropdownLinkItem",props:{item:{}},setup(e){const n=ws(e),{props:s,isExternal:r}=qo(n.item);return(o,i)=>(A(),H("div",Zc,[D("a",Ls({class:"item"},$(s)),[Qc,D("span",eu,xe(o.item.text),1),D("span",tu,[$(r)?(A(),ve(Hs,{key:0})):Z("",!0)])],16)]))}});var su=ue(nu,[["__scopeId","data-v-07381bdb"]]);const ru=["aria-label"],ou={class:"button-text"},iu={class:"dialog"},lu=se({__name:"NavDropdownLink",props:{item:{}},setup(e){const t=lt(),n=_t(!1);We(()=>t.path,()=>{n.value=!1});function s(){n.value=!n.value}return(r,o)=>(A(),H("div",{class:Ce(["nav-dropdown-link",{open:n.value}])},[D("button",{class:"button","aria-label":r.item.ariaLabel,onClick:s},[D("span",ou,xe(r.item.text),1),D("span",{class:Ce(["button-arrow",n.value?"down":"right"])},null,2)],8,ru),D("ul",iu,[(A(!0),H(de,null,Zt(r.item.items,i=>(A(),H("li",{key:i.text,class:"dialog-item"},[j(su,{item:i},null,8,["item"])]))),128))])],2))}});var Ar=ue(lu,[["__scopeId","data-v-18d75f62"]]);const au={key:0,class:"nav-links"},cu={key:1,class:"item"},uu={key:2,class:"item"},fu=se({__name:"NavLinks",setup(e){const{theme:t}=ge(),n=qc(),s=Yc(),r=W(()=>t.value.nav||s.value||n.value);return(o,i)=>r.value?(A(),H("nav",au,[$(t).nav?(A(!0),H(de,{key:0},Zt($(t).nav,l=>(A(),H("div",{key:l.text,class:"item"},[l.items?(A(),ve(Ar,{key:0,item:l},null,8,["item"])):(A(),ve($n,{key:1,item:l},null,8,["item"]))]))),128)):Z("",!0),$(n)?(A(),H("div",cu,[j(Ar,{item:$(n)},null,8,["item"])])):Z("",!0),$(s)?(A(),H("div",uu,[j($n,{item:$(s)},null,8,["item"])])):Z("",!0)])):Z("",!0)}});var zo=ue(fu,[["__scopeId","data-v-35b91e7e"]]);const du={emits:["toggle"]},hu=D("svg",{class:"icon",xmlns:"http://www.w3.org/2000/svg","aria-hidden":"true",role:"img",viewBox:"0 0 448 512"},[D("path",{fill:"currentColor",d:"M436 124H12c-6.627 0-12-5.373-12-12V80c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12z",class:""})],-1),pu=[hu];function _u(e,t,n,s,r,o){return A(),H("div",{class:"sidebar-button",onClick:t[0]||(t[0]=i=>e.$emit("toggle"))},pu)}var mu=ue(du,[["render",_u]]);const gu=e=>(Ss("data-v-40587210"),e=e(),Ts(),e),vu={class:"nav-bar"},bu=gu(()=>D("div",{class:"flex-grow"},null,-1)),yu={class:"nav"},xu=se({__name:"NavBar",emits:["toggle"],setup(e){return(t,n)=>(A(),H("header",vu,[j(mu,{onToggle:n[0]||(n[0]=s=>t.$emit("toggle"))}),j(Kc),bu,D("div",yu,[j(zo)]),ie(t.$slots,"search",{},void 0,!0)]))}});var wu=ue(xu,[["__scopeId","data-v-40587210"]]);function ku(){let e=null,t=null;const n=Au(s,300);function s(){const i=Cu(),l=Su(i);for(let a=0;a ul > li");l&&l!==t.parentElement?(e=l.querySelector("a"),e&&e.classList.add("active")):e=null}function o(i){i&&i.classList.remove("active")}bt(()=>{s(),window.addEventListener("scroll",n)}),mo(()=>{r(decodeURIComponent(location.hash))}),Nn(()=>{window.removeEventListener("scroll",n)})}function Cu(){return[].slice.call(document.querySelectorAll(".sidebar a.sidebar-link-item"))}function Su(e){return[].slice.call(document.querySelectorAll(".header-anchor")).filter(t=>e.some(n=>n.hash===t.hash))}function Tu(){return document.querySelector(".nav-bar").offsetHeight}function Ir(e){const t=Tu();return e.parentElement.offsetTop-t-15}function $u(e,t,n){const s=window.scrollY;return e===0&&s===0?[!0,null]:s{n&&clearTimeout(n),s?n=setTimeout(e,t):(e(),s=!0,setTimeout(()=>{s=!1},t))}}function Iu(){const e=lt(),{site:t}=ge();return ku(),W(()=>{const n=e.data.headers,s=e.data.frontmatter.sidebar,r=e.data.frontmatter.sidebarDepth;if(s===!1)return[];if(s==="auto")return Er(n,r);const o=Os(t.value.themeConfig.sidebar,e.data.relativePath);return o===!1?[]:o==="auto"?Er(n,r):o})}function Er(e,t){const n=[];if(e===void 0)return[];let s;return e.forEach(({level:r,title:o,slug:i})=>{if(r-1>t)return;const l={text:o,link:`#${i}`};r===2?(s=l,n.push(l)):s&&(s.children||(s.children=[])).push(l)}),n}const Yo=e=>{const t=lt(),{site:n,frontmatter:s}=ge(),r=e.depth||1,o=s.value.sidebarDepth||1/0,i=t.data.headers,l=e.item.text,a=Eu(n.value.base,e.item.link),u=e.item.children,d=oc(t,e.item.link),p=r0?mt("ul",{class:"sidebar-links"},t.map(r=>mt(Yo,{item:r,depth:s}))):e&&n?Go(!1,Lu(n),void 0,s):null}function Lu(e){return Jo(Pu(e))}function Pu(e){e=e.map(n=>Object.assign({},n));let t;return e.forEach(n=>{n.level===2?t=n:t&&(t.children||(t.children=[])).push(n)}),e.filter(n=>n.level===2)}function Jo(e){return e.map(t=>({text:t.title,link:`#${t.slug}`,children:t.children?Jo(t.children):void 0}))}const Ru={key:0,class:"sidebar-links"},Ou=se({__name:"SideBarLinks",setup(e){const t=Iu();return(n,s)=>$(t).length>0?(A(),H("ul",Ru,[(A(!0),H(de,null,Zt($(t),r=>(A(),ve($(Yo),{item:r},null,8,["item"]))),256))])):Z("",!0)}});const Hu=se({__name:"SideBar",props:{open:{type:Boolean}},setup(e){return(t,n)=>(A(),H("aside",{class:Ce(["sidebar",{open:t.open}])},[j(zo,{class:"nav"}),ie(t.$slots,"sidebar-top",{},void 0,!0),j(Ou),ie(t.$slots,"sidebar-bottom",{},void 0,!0)],2))}});var Mu=ue(Hu,[["__scopeId","data-v-17c48e2f"]]);const Du=/bitbucket.org/;function Nu(){const{page:e,theme:t,frontmatter:n}=ge(),s=W(()=>{const{repo:o,docsDir:i="",docsBranch:l="master",docsRepo:a=o,editLinks:u}=t.value,d=n.value.editLink!=null?n.value.editLink:u,{relativePath:p}=e.value;return!d||!p||!o?null:Fu(o,a,i,l,p)}),r=W(()=>t.value.editLinkText||"Edit this page");return{url:s,text:r}}function Fu(e,t,n,s,r){return Du.test(e)?ju(e,t,n,s,r):Uu(e,t,n,s,r)}function Uu(e,t,n,s,r){return(Rs(t)?t:`https://github.com/${t}`).replace(Tn,"")+`/edit/${s}/`+(n?n.replace(Tn,"")+"/":"")+r}function ju(e,t,n,s,r){return(Rs(t)?t:e).replace(Tn,"")+`/src/${s}/`+(n?n.replace(Tn,"")+"/":"")+r+`?mode=edit&spa=0&at=${s}&fileviewer=file-view-default`}const Bu={class:"edit-link"},Vu=["href"],Wu=se({__name:"EditLink",setup(e){const{url:t,text:n}=Nu();return(s,r)=>(A(),H("div",Bu,[$(t)?(A(),H("a",{key:0,class:"link",href:$(t),target:"_blank",rel:"noopener noreferrer"},[Qt(xe($(n))+" ",1),j(Hs,{class:"icon"})],8,Vu)):Z("",!0)]))}});var Ku=ue(Wu,[["__scopeId","data-v-55695e90"]]);const qu={key:0,class:"last-updated"},zu={class:"prefix"},Yu={class:"datetime"},Gu=se({__name:"LastUpdated",setup(e){const{theme:t,page:n}=ge(),s=W(()=>{const i=t.value.lastUpdated;return i!==void 0&&i!==!1&&n.value.lastUpdated!==0}),r=W(()=>{const i=t.value.lastUpdated;return i===!0?"Last Updated":i}),o=_t("");return bt(()=>{uo(()=>{o.value=new Date(n.value.lastUpdated).toLocaleString("en-US")})}),(i,l)=>s.value?(A(),H("p",qu,[D("span",zu,xe(r.value)+":",1),D("span",Yu,xe(o.value),1)])):Z("",!0)}});var Ju=ue(Gu,[["__scopeId","data-v-7e06cdca"]]);const Xu={class:"page-footer"},Zu={class:"edit"},Qu={class:"updated"},ef=se({__name:"PageFooter",setup(e){const{page:t}=ge();return(n,s)=>(A(),H("footer",Xu,[D("div",Zu,[j(Ku)]),D("div",Qu,[$(t).lastUpdated?(A(),ve(Ju,{key:0})):Z("",!0)])]))}});var tf=ue(ef,[["__scopeId","data-v-b65b4b36"]]);function nf(){const{page:e,theme:t}=ge(),n=W(()=>Wo(cs(e.value.relativePath))),s=W(()=>{const a=Os(t.value.sidebar,n.value);return Ps(a)?Ko(a):[]}),r=W(()=>s.value.findIndex(a=>a.link===n.value)),o=W(()=>{if(t.value.nextLinks!==!1&&r.value>-1&&r.value{if(t.value.prevLinks!==!1&&r.value>0)return s.value[r.value-1]}),l=W(()=>!!o.value||!!i.value);return{next:o,prev:i,hasLinks:l}}const sf={},rf={xmlns:"http://www.w3.org/2000/svg",viewBox:"0 0 24 24"},of=D("path",{d:"M19,11H7.4l5.3-5.3c0.4-0.4,0.4-1,0-1.4s-1-0.4-1.4,0l-7,7c-0.1,0.1-0.2,0.2-0.2,0.3c-0.1,0.2-0.1,0.5,0,0.8c0.1,0.1,0.1,0.2,0.2,0.3l7,7c0.2,0.2,0.5,0.3,0.7,0.3s0.5-0.1,0.7-0.3c0.4-0.4,0.4-1,0-1.4L7.4,13H19c0.6,0,1-0.4,1-1S19.6,11,19,11z"},null,-1),lf=[of];function af(e,t){return A(),H("svg",rf,lf)}var cf=ue(sf,[["render",af]]);const uf={},ff={xmlns:"http://www.w3.org/2000/svg",viewBox:"0 0 24 24"},df=D("path",{d:"M19.9,12.4c0.1-0.2,0.1-0.5,0-0.8c-0.1-0.1-0.1-0.2-0.2-0.3l-7-7c-0.4-0.4-1-0.4-1.4,0s-0.4,1,0,1.4l5.3,5.3H5c-0.6,0-1,0.4-1,1s0.4,1,1,1h11.6l-5.3,5.3c-0.4,0.4-0.4,1,0,1.4c0.2,0.2,0.5,0.3,0.7,0.3s0.5-0.1,0.7-0.3l7-7C19.8,12.6,19.9,12.5,19.9,12.4z"},null,-1),hf=[df];function pf(e,t){return A(),H("svg",ff,hf)}var _f=ue(uf,[["render",pf]]);const mf={key:0,class:"next-and-prev-link"},gf={class:"container"},vf={class:"prev"},bf=["href"],yf={class:"text"},xf={class:"next"},wf=["href"],kf={class:"text"},Cf=se({__name:"NextAndPrevLinks",setup(e){const{hasLinks:t,prev:n,next:s}=nf();return(r,o)=>$(t)?(A(),H("div",mf,[D("div",gf,[D("div",vf,[$(n)?(A(),H("a",{key:0,class:"link",href:$(Lt)($(n).link)},[j(cf,{class:"icon icon-prev"}),D("span",yf,xe($(n).text),1)],8,bf)):Z("",!0)]),D("div",xf,[$(s)?(A(),H("a",{key:0,class:"link",href:$(Lt)($(s).link)},[D("span",kf,xe($(s).text),1),j(_f,{class:"icon icon-next"})],8,wf)):Z("",!0)])])])):Z("",!0)}});var Sf=ue(Cf,[["__scopeId","data-v-e65a9748"]]);const Tf={class:"page"},$f={class:"container"},Af=se({__name:"Page",setup(e){return(t,n)=>{const s=At("Content");return A(),H("main",Tf,[D("div",$f,[ie(t.$slots,"top",{},void 0,!0),j(s,{class:"content"}),j(tf),j(Sf),ie(t.$slots,"bottom",{},void 0,!0)])])}}});var If=ue(Af,[["__scopeId","data-v-8fcebc32"]]);const Ef={key:0,id:"ads-container"},Lf=se({__name:"Layout",setup(e){const t=()=>null,n=t,s=t,r=t,o=lt(),{site:i,page:l,theme:a,frontmatter:u}=ge(),d=W(()=>!!u.value.customLayout),p=W(()=>!!u.value.home),b=W(()=>Object.keys(i.value.langs).length>1),C=W(()=>{const h=a.value;return u.value.navbar===!1||h.navbar===!1?!1:i.value.title||h.logo||h.repo||h.nav}),M=_t(!1),V=W(()=>u.value.home||u.value.sidebar===!1?!1:!cc(Os(a.value.sidebar,o.data.relativePath))),ce=h=>{M.value=typeof h=="boolean"?h:!M.value},re=ce.bind(null,!1);We(o,re);const ae=W(()=>[{"no-navbar":!C.value,"sidebar-open":M.value,"no-sidebar":!V.value}]);return(h,y)=>{const O=At("Content"),I=At("Debug");return A(),H(de,null,[D("div",{class:Ce(["theme",ae.value])},[C.value?(A(),ve(wu,{key:0,onToggle:ce},{search:Pe(()=>[ie(h.$slots,"navbar-search",{},()=>[$(a).algolia?(A(),ve($(r),{key:0,options:$(a).algolia,multilang:b.value},null,8,["options","multilang"])):Z("",!0)])]),_:3})):Z("",!0),j(Mu,{open:M.value},{"sidebar-top":Pe(()=>[ie(h.$slots,"sidebar-top")]),"sidebar-bottom":Pe(()=>[ie(h.$slots,"sidebar-bottom")]),_:3},8,["open"]),D("div",{class:"sidebar-mask",onClick:y[0]||(y[0]=K=>ce(!1))}),d.value?(A(),ve(O,{key:1})):p.value?ie(h.$slots,"home",{key:2},()=>[j(jc,null,{hero:Pe(()=>[ie(h.$slots,"home-hero")]),features:Pe(()=>[ie(h.$slots,"home-features")]),footer:Pe(()=>[ie(h.$slots,"home-footer")]),_:3})]):(A(),ve(If,{key:3},{top:Pe(()=>[ie(h.$slots,"page-top-ads",{},()=>[$(a).carbonAds&&$(a).carbonAds.carbon?(A(),H("div",Ef,[(A(),ve($(n),{key:"carbon"+$(l).relativePath,code:$(a).carbonAds.carbon,placement:$(a).carbonAds.placement},null,8,["code","placement"]))])):Z("",!0)]),ie(h.$slots,"page-top")]),bottom:Pe(()=>[ie(h.$slots,"page-bottom"),ie(h.$slots,"page-bottom-ads",{},()=>[$(a).carbonAds&&$(a).carbonAds.custom?(A(),ve($(s),{key:"custom"+$(l).relativePath,code:$(a).carbonAds.custom,placement:$(a).carbonAds.placement},null,8,["code","placement"])):Z("",!0)])]),_:3}))],2),j(I)],64)}}}),Pf={class:"theme"},Rf=D("h1",null,"404",-1),Of=["href"],Hf=se({__name:"NotFound",setup(e){const{site:t}=ge(),n=["There's nothing here.","How did we get here?","That's a Four-Oh-Four.","Looks like we've got some broken links."];function s(){return n[Math.floor(Math.random()*n.length)]}return(r,o)=>(A(),H("div",Pf,[Rf,D("blockquote",null,xe(s()),1),D("a",{href:$(t).base,"aria-label":"go to home"},"Take me home.",8,Of)]))}}),Mf={Layout:Lf,NotFound:Hf},Xo=Symbol("addTab"),Zo=Symbol("updateTab"),Qo=Symbol("deleteTab"),ei=Symbol("tabsProvider");function fn(e,t){const n=pt(e,t);if(typeof n>"u")throw new Error(`Could not resolve ${e.description}`);return n}const Df=["data-tab-id","aria-hidden"],Nf=se({__name:"Tab",props:{panelClass:{default:"tabs-component-panel"},id:{default:void 0},name:null,prefix:{default:""},suffix:{default:""},isDisabled:{type:Boolean,default:!1},navItemClass:{default:void 0},navItemLinkClass:{default:void 0}},setup(e,{expose:t}){const n=e,s=_t(!1),r=fn(ei),o=fn(Xo),i=fn(Zo),l=fn(Qo),a=n.prefix+n.name+n.suffix,u=n.id?n.id:n.name.toLowerCase().replace(/ /g,"-"),d=u+"-pane",p=W(()=>"#"+(n.isDisabled?"":u));return We(()=>r.activeTabHash,()=>{s.value=p.value===r.activeTabHash}),We(()=>Object.assign({},n),()=>{i(u,{name:n.name,header:n.prefix+n.name+n.suffix,isDisabled:n.isDisabled,hash:p.value,index:r.tabs.length,computedId:u,paneId:d,navItemClass:n.navItemClass,navItemLinkClass:n.navItemLinkClass})}),_o(()=>{o({name:n.name,header:a,isDisabled:n.isDisabled,hash:p.value,index:r.tabs.length,computedId:u,paneId:d,navItemClass:n.navItemClass,navItemLinkClass:n.navItemLinkClass})}),go(()=>{l(u)}),t({header:a,computedId:u,paneId:d,hash:p,isActive:s}),(b,C)=>vl((A(),H("section",{ref:"tab",id:d,"data-tab-id":$(u),"aria-hidden":!s.value,class:Ce(e.panelClass),role:"tabpanel",tabindex:"-1"},[ie(b.$slots,"default")],10,Df)),[[ma,s.value]])}});class Ff{get(t){const n=localStorage.getItem(t);if(n===null)return null;const s=JSON.parse(n);return s?new Date(s.expires)({useUrlFragment:!0,defaultTabHash:void 0,storageKey:void 0})},wrapperClass:{default:"tabs-component"},panelsWrapperClass:{default:"tabs-component-panels"},navClass:{default:"tabs-component-tabs"},navItemClass:{default:"tabs-component-tab"},navItemDisabledClass:{default:"is-disabled"},navItemActiveClass:{default:"is-active"},navItemInactiveClass:{default:"is-inactive"},navItemLinkClass:{default:"tabs-component-tab-a"},navItemLinkActiveClass:{default:"is-active"},navItemLinkInactiveClass:{default:"is-inactive"},navItemLinkDisabledClass:{default:"is-disabled"}},emits:["changed","clicked"],setup(e,{expose:t,emit:n}){const s=e,r=Rt({activeTabHash:"",lastActiveTabHash:"",tabs:[]});Ft(ei,r),Ft(Xo,a=>{r.tabs.push(a)}),Ft(Zo,(a,u)=>{const d=r.tabs.findIndex(p=>p.computedId===a);u.isActive=r.tabs[d].isActive,r.tabs[d]=u}),Ft(Qo,a=>{const u=r.tabs.findIndex(d=>d.computedId===a);r.tabs.splice(u,1)});const o=W(()=>{let a;return s.options.storageKey&&(a=s.options.storageKey),!a&&s.id&&(a=`vue-tabs-component.${s.id}.cache.${window.location.host}${window.location.pathname}`),a||(a=`vue-tabs-component.cache.${window.location.host}${window.location.pathname}`),a}),i=(a,u)=>{u&&!s.options.useUrlFragment&&u.preventDefault();const d=l(a);if(d){if(u&&d.isDisabled){u.preventDefault();return}if(r.lastActiveTabHash===d.hash){n("clicked",{tab:d});return}r.tabs.forEach(p=>{p.isActive=p.hash===d.hash}),n("changed",{tab:d}),r.lastActiveTabHash=r.activeTabHash=d.hash,!(s.cacheLifetime<=0)&&Lr.set(o.value,d.hash,s.cacheLifetime)}},l=a=>r.tabs.find(u=>u.hash===a);return bt(()=>{if(r.tabs.length){if(window.addEventListener("hashchange",()=>i(window.location.hash)),l(window.location.hash)){i(window.location.hash);return}if(s.cacheLifetime>0){const a=Lr.get(o.value);if(a!==null&&l(a)){i(a);return}}if(s.options.defaultTabHash&&l("#"+s.options.defaultTabHash)){i("#"+s.options.defaultTabHash);return}i(r.tabs[0].hash)}}),t({...ws(r),selectTab:i,findTab:l}),(a,u)=>(A(),H("div",{class:Ce(e.wrapperClass),id:e.id},[D("ul",{role:"tablist",class:Ce(e.navClass)},[(A(!0),H(de,null,Zt(r.tabs,(d,p)=>{var b,C;return A(),H("li",{key:p,class:Ce([(b=d.navItemClass)!=null?b:e.navItemClass,d.isDisabled?e.navItemDisabledClass:"",d.isActive?e.navItemActiveClass:d.isDisabled?"":e.navItemInactiveClass]),role:"presentation"},[D("a",{role:"tab",class:Ce([(C=d.navItemLinkClass)!=null?C:e.navItemLinkClass,d.isDisabled?e.navItemLinkDisabledClass:"",d.isActive?e.navItemLinkActiveClass:d.isDisabled?"":e.navItemLinkInactiveClass]),"aria-controls":d.paneId,"aria-selected":d.isActive,href:d.hash,onClick:M=>i(d.hash,M),innerHTML:d.header,tabindex:"0"},null,10,jf)],2)}),128))],2),D("div",{class:Ce(e.panelsWrapperClass)},[ie(a.$slots,"default")],2)],10,Uf))}}),Vf={props:{id:{type:String,default:null}},computed:{anId(){return this.id+"-an"},atId(){return this.id+"-at"}}};function Wf(e,t,n,s,r,o){const i=At("tab"),l=At("tabs");return A(),H("div",null,[j(l,{options:{useUrlFragment:!1}},{default:Pe(()=>[j(i,{id:o.anId,name:"Annotations"},{default:Pe(()=>[ie(e.$slots,"an")]),_:3},8,["id"]),j(i,{id:o.atId,name:"Attributes"},{default:Pe(()=>[ie(e.$slots,"at")]),_:3},8,["id"])]),_:3})])}var Kf=ue(Vf,[["render",Wf]]);var An={...Mf,enhanceApp({app:e,router:t,siteData:n}){e.component("tabs",Bf),e.component("tab",Nf),e.component("codeblock",Kf)}};const Qn=new Set,ti=()=>document.createElement("link"),qf=e=>{const t=ti();t.rel="prefetch",t.href=e,document.head.appendChild(t)},zf=e=>{const t=new XMLHttpRequest;t.open("GET",e,t.withCredentials=!0),t.send()};let dn;const Yf=De&&(dn=ti())&&dn.relList&&dn.relList.supports&&dn.relList.supports("prefetch")?qf:zf;function Gf(){if(!De||!window.IntersectionObserver)return;let e;if((e=navigator.connection)&&(e.saveData||/2g/.test(e.effectiveType)))return;const t=window.requestIdleCallback||setTimeout;let n=null;const s=()=>{n&&n.disconnect(),n=new IntersectionObserver(o=>{o.forEach(i=>{if(i.isIntersecting){const l=i.target;n.unobserve(l);const{pathname:a}=l;if(!Qn.has(a)){Qn.add(a);const u=jo(a);Yf(u)}}})}),t(()=>{document.querySelectorAll("#app a").forEach(o=>{const{target:i,hostname:l,pathname:a}=o,u=a.match(/\.\w+$/);u&&u[0]!==".html"||i!=="_blank"&&l===location.hostname&&(a!==location.pathname?n.observe(o):Qn.add(a))})})};bt(s);const r=lt();We(()=>r.path,s),Nn(()=>{n&&n.disconnect()})}const Jf=se({setup(e,{slots:t}){const n=_t(!1);return bt(()=>{n.value=!0}),()=>n.value&&t.default?t.default():null}}),Xf=An.NotFound||(()=>"404 Not Found"),Zf={name:"VitePressApp",setup(){const{site:e}=ge();return bt(()=>{We(()=>e.value.lang,t=>{document.documentElement.lang=t},{immediate:!0})}),Gf(),()=>mt(An.Layout)}};function Qf(){const e=td(),t=ed();t.provide(Bo,e);const n=Wa(e.route);return t.provide(Uo,n),t.component("Content",Za),t.component("ClientOnly",Jf),t.component("Debug",()=>null),Object.defineProperty(t.config.globalProperties,"$frontmatter",{get(){return n.frontmatter.value}}),An.enhanceApp&&An.enhanceApp({app:t,router:e,siteData:tn}),{app:t,router:e,data:n}}function ed(){return Ha(Zf)}function td(){let e=De,t;return za(n=>{let s=jo(n);return e&&(t=s),(e||t===s)&&(s=s.replace(/\.js$/,".lean.js")),De?(e=!1,ii(()=>import(s),[])):require(s)},Xf)}if(De){const{app:e,router:t,data:n}=Qf();t.go().then(()=>{Ga(t.route,n.site),e.mount("#app")})}export{ue as _,nd as a,j as b,H as c,Qf as createApp,D as d,Qt as e,A as o,At as r,Pe as w}; diff --git a/assets/guide_annotations.md.b48e8efc.js b/assets/guide_annotations.md.b48e8efc.js new file mode 100644 index 000000000..0b5355216 --- /dev/null +++ b/assets/guide_annotations.md.b48e8efc.js @@ -0,0 +1,76 @@ +import{_ as n,c as s,o as a,a as t}from"./app.d3800f98.js";const q='{"title":"Annotations","description":"","frontmatter":{},"headers":[{"level":2,"title":"Doctrine","slug":"doctrine"},{"level":2,"title":"Escaping","slug":"escaping"},{"level":2,"title":"Arrays and Objects","slug":"arrays-and-objects"},{"level":2,"title":"Constants","slug":"constants"}],"relativePath":"guide/annotations.md"}',o={},e=t(`

Annotations

Namespace

Using a namespace alias simplifies typing and improves readability.

All annotations are in the OpenApi\\Annotations namespace.

Since Annotations are technically PHP comments, adding use OpenApi\\Annotations as OA; is strictly speaking not necessary. However, doctrine will be quite specific about whether an alias is valid or not.

swagger-php will automatically register the @OA alias so all annotations can be used using the @OA shortcut without any additional work.

Doctrine

Annotations are PHP comments (docblocks) containing doctrine style annotations.

INFO

All documentation related to doctrine applies to annotations only.

Example:

<?php
+
+use OpenApi\\Annotations as OA;
+
+/**
+ * @OA\\Info(title="My First API", version="0.1")
+ */
+class OpenApi {}
+
+class MyController {
+
+    /**
+     * @OA\\Get(
+     *     path="/api/resource.json",
+     *     @OA\\Response(response="200", description="An example resource")
+     * )
+     */
+    public function resource() {
+        // ...
+    }
+}
+

Escaping

Escaping double quotes

Double quotes can be escaped by doubling them rather than using \\

For example:

    @OA\\Schema(
+       title="Request",
+       schema="Request",
+       example={
+          "configuration":"{""formConfig"":123}"
+       }
+     )
+

Arrays and Objects

Doctrine annotations support arrays, but use { and } instead of [ and ].

Doctrine also supports objects, which also use { and } and require the property names to be surrounded with ".

DON'T WRITE

/**
+ * @OA\\Info(
+ *   title="My first API",
+ *   version="1.0.0",
+ *   contact={
+ *     "email": "support@example.com"
+ *   }
+ * )
+ */
+

This "works" but most objects have an annotation with the same name as the property, such as @OA\\Contact for contact:

WRITE

/**
+ * @OA\\Info(
+ *   title="My first API",
+ *   version="1.0.0",
+ *   @OA\\Contact(
+ *     email="support@example.com"
+ *   )
+ * )
+ */
+

This also adds validation, so when you misspell a property or forget a required property, it will trigger a PHP warning.

For example, if you write emial="support@example.com", swagger-php would generate a notice with Unexpected field "emial" for @OA\\Contact(), expecting "name", "email", ...

Placing multiple annotations of the same type will result in an array of objects. For objects, the key is defined by the field with the same name as the annotation: response in a @OA\\Response, property in a @OA\\Property, etc.

/**
+ * @OA\\Get(
+ *   path="/products",
+ *   summary="list products",
+ *   @OA\\Response(
+ *     response=200,
+ *     description="A list with products"
+ *   ),
+ *   @OA\\Response(
+ *     response="default",
+ *     description="an ""unexpected"" error"
+ *   )
+ * )
+ */
+

Results in

openapi: 3.0.0
+paths:
+  /products:
+    get:
+      summary: "list products"
+      responses:
+        "200":
+          description: "A list with products"
+        default:
+          description: 'an "unexpected" error'
+

Constants

You can use constants inside doctrine annotations.

define("API_HOST", ($env === "production") ? "example.com" : "localhost");
+
/**
+ * @OA\\Server(url=API_HOST)
+ */
+

TIP

Using the CLI you might need to include the php file with the constants using the --bootstrap options.

> openapi --bootstrap constants.php
+
`,28),p=[e];function c(i,l,u,r,d,k){return a(),s("div",null,p)}var g=n(o,[["render",c]]);export{q as __pageData,g as default}; diff --git a/assets/guide_annotations.md.b48e8efc.lean.js b/assets/guide_annotations.md.b48e8efc.lean.js new file mode 100644 index 000000000..fd97f6b6b --- /dev/null +++ b/assets/guide_annotations.md.b48e8efc.lean.js @@ -0,0 +1 @@ +import{_ as n,c as s,o as a,a as t}from"./app.d3800f98.js";const q='{"title":"Annotations","description":"","frontmatter":{},"headers":[{"level":2,"title":"Doctrine","slug":"doctrine"},{"level":2,"title":"Escaping","slug":"escaping"},{"level":2,"title":"Arrays and Objects","slug":"arrays-and-objects"},{"level":2,"title":"Constants","slug":"constants"}],"relativePath":"guide/annotations.md"}',o={},e=t("",28),p=[e];function c(i,l,u,r,d,k){return a(),s("div",null,p)}var g=n(o,[["render",c]]);export{q as __pageData,g as default}; diff --git a/assets/guide_attributes.md.b0468df2.js b/assets/guide_attributes.md.b0468df2.js new file mode 100644 index 000000000..757a95586 --- /dev/null +++ b/assets/guide_attributes.md.b0468df2.js @@ -0,0 +1,13 @@ +import{_ as s,c as n,o as a,a as t}from"./app.d3800f98.js";const b='{"title":"Attributes","description":"","frontmatter":{},"headers":[{"level":2,"title":"Nesting","slug":"nesting"}],"relativePath":"guide/attributes.md"}',e={},p=t(`

Attributes

Namespace

Using a namespace alias simplifies typing and improves readability.

All attributes are in the OpenApi\\Attributes namespace.

Nesting

Similar to annotations attributes can be top level or nested. However, attributes may be put at the same level if there is no ambiguity. swagger-php will then merge attributes according to the defined rules about parent/child relationships.

Example

Nested:

    #[OA\\Get(
+        path: '/api/users',
+        responses: [
+            new OA\\Response(response: 200, description: 'AOK'),
+            new OA\\Response(response: 401, description: 'Not allowed'),
+        ]
+    )]
+    public function users() { /* ... */ }
+

Not nested:

    #[OA\\Get(path: '/api/users')]
+    #[OA\\Response(response: 200, description: 'AOK')]
+    #[OA\\Response(response: 401, description: 'Not allowed')]
+    public function users() { /* ... */ }
+

Depending on how much nesting there is this can make things a bit simpler and easier to read.

Top level only

Automatic merging of attributes works only at the top level - in the example that would be the method users().

`,11),c=[p];function o(i,l,u,r,k,m){return a(),n("div",null,c)}var g=s(e,[["render",o]]);export{b as __pageData,g as default}; diff --git a/assets/guide_attributes.md.b0468df2.lean.js b/assets/guide_attributes.md.b0468df2.lean.js new file mode 100644 index 000000000..b3a3db5ce --- /dev/null +++ b/assets/guide_attributes.md.b0468df2.lean.js @@ -0,0 +1 @@ +import{_ as s,c as n,o as a,a as t}from"./app.d3800f98.js";const b='{"title":"Attributes","description":"","frontmatter":{},"headers":[{"level":2,"title":"Nesting","slug":"nesting"}],"relativePath":"guide/attributes.md"}',e={},p=t("",11),c=[p];function o(i,l,u,r,k,m){return a(),n("div",null,c)}var g=s(e,[["render",o]]);export{b as __pageData,g as default}; diff --git a/assets/guide_common-techniques.md.c3d11b39.js b/assets/guide_common-techniques.md.c3d11b39.js new file mode 100644 index 000000000..38c79ce37 --- /dev/null +++ b/assets/guide_common-techniques.md.c3d11b39.js @@ -0,0 +1,216 @@ +import{_ as n,c as s,o as a,a as e}from"./app.d3800f98.js";const h='{"title":"Common techniques","description":"","frontmatter":{},"headers":[{"level":2,"title":"Annotation placement","slug":"annotation-placement"},{"level":2,"title":"Context awareness","slug":"context-awareness"},{"level":2,"title":"Response media type","slug":"response-media-type"},{"level":2,"title":"Using references - $ref","slug":"using-references-ref"},{"level":2,"title":"Array parameters in query","slug":"array-parameters-in-query"},{"level":2,"title":"Vendor extensions","slug":"vendor-extensions"},{"level":2,"title":"Enums","slug":"enums"},{"level":3,"title":"Enum cases as value","slug":"enum-cases-as-value"},{"level":2,"title":"Enum schemas","slug":"enum-schemas"}],"relativePath":"guide/common-techniques.md"}',t={},p=e(`

Common techniques

Annotation placement

You shouldn't place all annotations inside one big block, but scatter them throughout your codebase as close to the relevant source code as appropriate.

swagger-php will scan your project and merge all meta-data into one @OA\\OpenApi annotation.

WARNING

As of swagger-php v4 all annotations or attributes must be associated with a structural element (class, method, parameter or enum)

Context awareness

swagger-php looks at the context of the annotation and will augment it with things like property name, data type (doctype and native type hints) as well as a couple other things.

This means in a lot of cases it is not necessary to explicitly document all details.

Example

<?php
+
+/**
+ * @OA\\Schema()
+ */
+class Product {
+
+    /**
+     * The product name,
+     * @var string
+     * @OA\\Property()
+     */
+    public $name;
+}
+

Results in

openapi: 3.0.0
+components:
+  schemas:
+    Product:
+      properties:
+        name:
+          description: "The product name"
+          type: string
+      type: object
+

As if you'd written

    /**
+     * The product name
+     * @var string
+     *
+     * @OA\\Property(
+     *   property="name",
+     *   type="string",
+     *   description="The product name"
+     * )
+     */
+    public $name;
+

Response media type

The @OA\\MediaType is used to describe the content:

/**
+ * @OA\\Response(
+ *     response=200,
+ *     description="successful operation",
+ *     @OA\\MediaType(
+ *         mediaType="application/json",
+ *         @OA\\Schema(ref="#/components/schemas/User"),
+ *     )
+ * ),
+ */
+

But because most API requests and responses are JSON, the @OA\\JsonContent allows you to simplify this by writing:

/**
+ * @OA\\Response(
+ *     response=200,
+ *     description="successful operation",
+ *     @OA\\JsonContent(ref="#/components/schemas/User"),
+ * )
+ */
+

During processing the @OA\\JsonContent unfolds to @OA\\MediaType( mediaType="application/json", @OA\\Schema(...) and will generate the same output.

Using references - $ref

It's quite common that endpoints have some overlap in either their request or response data. To keep things DRY (Don't Repeat Yourself) the specification allows reusing components using $ref's

/**
+ * @OA\\Schema(
+ *   schema="product_id",
+ *   type="integer",
+ *   format="int64",
+ *   description="The unique identifier of a product in our catalog"
+ * )
+ */
+

Results in:

openapi: 3.0.0
+components:
+  schemas:
+    product_id:
+      description: "The unique identifier of a product in our catalog"
+      type: integer
+      format: int64
+

This doesn't do anything by itself, but now you can reference this fragment by its path in the document tree #/components/schemas/product_id

    /**
+     * @OA\\Property(ref="#/components/schemas/product_id")
+     */
+    public $id;
+

Examples

There are more uses cases on how to use refs in the using-refs example.

Array parameters in query

Depending on style-values @OA\\Parameter(in="query", name="param", ...) might create urls like this: path?param=123&param=abc which do not work when reading the param values in PHP.

The solution is to change the name param into param[] which will create path?param[]=123&param[]=abc and results in a PHP array.

Vendor extensions

The specification allows for custom properties as long as they start with "x-". Therefore, all swagger-php annotations have an x property which accepts an array (map) and will unfold into "x-" properties.

/**
+ * @OA\\Info(
+ *   title="Example",
+ *   version="1.0.0",
+ *   x={
+ *     "some-name": "a-value",
+ *     "another": 2,
+ *     "complex-type": {
+ *       "supported":{
+ *         {"version": "1.0", "level": "baseapi"},
+ *         {"version": "2.1", "level": "fullapi"},
+ *       }
+ *     }
+ *   }
+ * )
+ */
+

Results in:

openapi: 3.0.0
+info:
+  title: Example
+  version: 1
+  x-some-name: a-value
+  x-another: 2
+  x-complex-type:
+    supported:
+      - version: "1.0"
+        level: baseapi
+      - version: "2.1"
+        level: fullapi
+

Enums

PHP 8.1 enums are supported in two main use cases.

Enum cases as value

Enum cases can be used as value in an enum list just like a string, integer or any other primitive type.

Basic enum:

use OpenApi\\Attributes as OAT;
+
+enum Suit
+{
+    case Hearts;
+    case Diamonds;
+    case Clubs;
+    case Spades;
+}
+
+class Model
+{
+    #[OAT\\Property(enum: [Suit::Hearts, Suit::Diamonds])]
+    protected array $someSuits;
+}
+

Results in:

openapi: 3.0.0
+components:
+  schemas:
+    Model:
+      properties:
+        someSuits:
+          type: array
+          enum:
+            - Hearts
+            - Diamonds
+      type: object
+
+

Backed enums

If the enum is a backed enum, the case backing value is used instead of the name.

Enum schemas

The simples way of using enums is to annotate them as Schema. This allows you to reference them like any other schema in your spec.

use OpenApi\\Attributes as OAT;
+
+#[OAT\\Schema()]
+enum Colour
+{
+    case GREEN;
+    case BLUE;
+    case RED;
+}
+
+#[OAT\\Schema()]
+class Product
+{
+    #[OAT\\Property()]
+    public Colour $colour;
+}
+

Results in:

openapi: 3.0.0
+components:
+  schemas:
+    Colour:
+      type: string
+      enum:
+        - GREEN
+        - BLUE
+        - RED
+    Product:
+      properties:
+        colour:
+          $ref: '#/components/schemas/Colour'
+      type: object
+

Backed enums

For backed enums there exist two rules that determine whether the name or backing value is used:

  1. If no schema type is given, the enum name is used.
  2. If a schema type is given, and it matches the backing type, the enum backing value is used.

Using the name of a backed enum:

use OpenApi\\Attributes as OAT;
+
+#[OAT\\Schema()]
+enum Colour: int
+{
+    case GREEN = 1;
+    case BLUE = 2;
+    case RED = 3;
+}
+
+#[OAT\\Schema()]
+class Product
+{
+    #[OAT\\Property()]
+    public Colour $colour;
+}
+

Results in:

openapi: 3.0.0
+components:
+  schemas:
+    Colour:
+      type: string
+      enum:
+        - GREEN
+        - BLUE
+        - RED
+    Product:
+      properties:
+        colour:
+          $ref: '#/components/schemas/Colour'
+      type: object
+

Using the backing value:

use OpenApi\\Attributes as OAT;
+
+#[OAT\\Schema(type: 'integer')]
+enum Colour: int
+{
+    case GREEN = 1;
+    case BLUE = 2;
+    case RED = 3;
+}
+
+#[OAT\\Schema()]
+class Product
+{
+    #[OAT\\Property()]
+    public Colour $colour;
+}
+

Results in:

openapi: 3.0.0
+components:
+  schemas:
+    Colour:
+      type: integer
+      enum:
+        - 1
+        - 2
+        - 3
+    Product:
+      properties:
+        colour:
+          $ref: '#/components/schemas/Colour'
+      type: object
+
`,62),o=[p];function c(l,u,i,r,k,d){return a(),s("div",null,o)}var y=n(t,[["render",c]]);export{h as __pageData,y as default}; diff --git a/assets/guide_common-techniques.md.c3d11b39.lean.js b/assets/guide_common-techniques.md.c3d11b39.lean.js new file mode 100644 index 000000000..edc174cc4 --- /dev/null +++ b/assets/guide_common-techniques.md.c3d11b39.lean.js @@ -0,0 +1 @@ +import{_ as n,c as s,o as a,a as e}from"./app.d3800f98.js";const h='{"title":"Common techniques","description":"","frontmatter":{},"headers":[{"level":2,"title":"Annotation placement","slug":"annotation-placement"},{"level":2,"title":"Context awareness","slug":"context-awareness"},{"level":2,"title":"Response media type","slug":"response-media-type"},{"level":2,"title":"Using references - $ref","slug":"using-references-ref"},{"level":2,"title":"Array parameters in query","slug":"array-parameters-in-query"},{"level":2,"title":"Vendor extensions","slug":"vendor-extensions"},{"level":2,"title":"Enums","slug":"enums"},{"level":3,"title":"Enum cases as value","slug":"enum-cases-as-value"},{"level":2,"title":"Enum schemas","slug":"enum-schemas"}],"relativePath":"guide/common-techniques.md"}',t={},p=e("",62),o=[p];function c(l,u,i,r,k,d){return a(),s("div",null,o)}var y=n(t,[["render",c]]);export{h as __pageData,y as default}; diff --git a/assets/guide_cookbook.md.58253880.js b/assets/guide_cookbook.md.58253880.js new file mode 100644 index 000000000..bda92d4a2 --- /dev/null +++ b/assets/guide_cookbook.md.58253880.js @@ -0,0 +1,496 @@ +import{_ as o,c as p,b as c,w as a,a as e,r as u,o as l,d as n,e as s}from"./app.d3800f98.js";const O='{"title":"Cookbook","description":"","frontmatter":{},"headers":[{"level":2,"title":"x-tagGroups","slug":"x-taggroups"},{"level":2,"title":"Adding examples to @OA\\\\Response","slug":"adding-examples-to-oa-response"},{"level":2,"title":"External documentation","slug":"external-documentation"},{"level":2,"title":"Properties with union types","slug":"properties-with-union-types"},{"level":2,"title":"Referencing a security scheme","slug":"referencing-a-security-scheme"},{"level":2,"title":"File upload with headers","slug":"file-upload-with-headers"},{"level":2,"title":"Set the XML root name","slug":"set-the-xml-root-name"},{"level":2,"title":"upload multipart/form-data","slug":"upload-multipart-form-data"},{"level":2,"title":"Default security scheme for all endpoints","slug":"default-security-scheme-for-all-endpoints"},{"level":2,"title":"Nested objects","slug":"nested-objects"},{"level":2,"title":"Documenting union type response data using oneOf","slug":"documenting-union-type-response-data-using-oneof"},{"level":2,"title":"Reusing responses","slug":"reusing-responses"},{"level":2,"title":"mediaType=\\"/\\"","slug":"mediatype"},{"level":2,"title":"Warning about Multiple response with same response=\\"200\\"","slug":"warning-about-multiple-response-with-same-response-200"},{"level":2,"title":"Callbacks","slug":"callbacks"},{"level":2,"title":"(Mostly) virtual models","slug":"mostly-virtual-models"},{"level":2,"title":"Using class name as type instead of references","slug":"using-class-name-as-type-instead-of-references"},{"level":2,"title":"Enums","slug":"enums"},{"level":2,"title":"Multi value query parameter: &q[]=1&q[]=1","slug":"multi-value-query-parameter-q-1-q-1"},{"level":2,"title":"Custom response classes","slug":"custom-response-classes"},{"level":2,"title":"Annotating class constants","slug":"annotating-class-constants"}],"relativePath":"guide/cookbook.md"}',i={},r=e(`

Cookbook

x-tagGroups

OpenApi has the concept of grouping endpoints using tags. On top of that, some tools (redocly, for example) support further grouping via the vendor extension x-tagGroups.

/**
+ * @OA\\OpenApi(
+ *   x={
+ *       "tagGroups"=
+ *           {{"name"="User Management", "tags"={"Users", "API keys", "Admin"}}
+ *       }
+ *   }
+ * )
+ */
+

Adding examples to @OA\\Response 

/*
+ * @OA\\Response(
+ *     response=200,
+ *     description="OK",
+ *     @OA\\JsonContent(
+ *         oneOf={
+ *             @OA\\Schema(ref="#/components/schemas/Result"),
+ *             @OA\\Schema(type="boolean")
+ *         },
+ *         @OA\\Examples(example="result", value={"success": true}, summary="An result object."),
+ *         @OA\\Examples(example="bool", value=false, summary="A boolean value."),
+ *     )
+ * )
+ */
+

External documentation

OpenApi allows a single reference to external documentation. This is a part of the top level @OA\\OpenApi.

/**
+ * @OA\\OpenApi(
+ *   @OA\\ExternalDocumentation(
+ *     description="More documentation here...",
+ *     url="https://example.com/externaldoc1/"
+ *   )
+ * )
+ */
+

TIP

If no @OA\\OpenApi is configured, swagger-php will create one automatically.

That means the above example would also work with just the OA\\ExternalDocumentation annotation.

/**
+ * @OA\\ExternalDocumentation(
+ *   description="More documentation here...",
+ *   url="https://example.com/externaldoc1/"
+ * )
+ */
+

Properties with union types

Sometimes properties or even lists (arrays) may contain data of different types. This can be expressed using oneOf.

/**
+ * @OA\\Schema(
+ *      schema="StringList",
+ *      @OA\\Property(property="value", type="array", @OA\\Items(anyOf={@OA\\Schema(type="string")}))
+ * )
+ * @OA\\Schema(
+ *      schema="String",
+ *      @OA\\Property(property="value", type="string")
+ * )
+ * @OA\\Schema(
+ *      schema="Object",
+ *      @OA\\Property(property="value", type="object")
+ * )
+ * @OA\\Schema(
+ *     schema="mixedList",
+ *     @OA\\Property(property="fields", type="array", @OA\\Items(oneOf={
+ *         @OA\\Schema(ref="#/components/schemas/StringList"),
+ *         @OA\\Schema(ref="#/components/schemas/String"),
+ *         @OA\\Schema(ref="#/components/schemas/Object")
+ *     }))
+ * )
+ */
+

This will resolve into this YAML

openapi: 3.0.0
+components:
+  schemas:
+    StringList:
+      properties:
+        value:
+          type: array
+          items:
+            anyOf:
+              -
+                type: string
+      type: object
+    String:
+      properties:
+        value:
+          type: string
+      type: object
+    Object:
+      properties:
+        value:
+          type: object
+      type: object
+    mixedList:
+      properties:
+        fields:
+          type: array
+          items:
+            oneOf:
+              -
+                $ref: '#/components/schemas/StringList'
+              -
+                $ref: '#/components/schemas/String'
+              -
+                $ref: '#/components/schemas/Object'
+      type: object
+

Referencing a security scheme

An API might have zero or more security schemes. These are defined at the top level and vary from simple to complex:

/**
+ * @OA\\SecurityScheme(
+ *     type="apiKey",
+ *     name="api_key",
+ *     in="header",
+ *     securityScheme="api_key"
+ * )
+ *
+ * @OA\\SecurityScheme(
+ *   type="oauth2",
+ *   securityScheme="petstore_auth",
+ *   @OA\\Flow(
+ *      authorizationUrl="http://petstore.swagger.io/oauth/dialog",
+ *      flow="implicit",
+ *      scopes={
+ *         "read:pets": "read your pets",
+ *         "write:pets": "modify pets in your account"
+ *      }
+ *   )
+ * )
+ */
+

To declare an endpoint as secure and define what security schemes are available to authenticate a client it needs to be added to the operation, for example:

/**
+ * @OA\\Get(
+ *      path="/api/secure/",
+ *      summary="Requires authentication"
+ *    ),
+ *    security={ {"api_key": {}} }
+ * )
+ */
+

Endpoints can support multiple security schemes and have custom options too:

/**
+ * @OA\\Get(
+ *      path="/api/secure/",
+ *      summary="Requires authentication"
+ *    ),
+ *    security={
+ *      { "api_key": {} },
+ *      { "petstore_auth": {"write:pets", "read:pets"} }
+ *    }
+ * )
+ */
+

File upload with headers 

/**
+ * @OA\\Post(
+ *   path="/v1/media/upload",
+ *   summary="Upload document",
+ *   description="",
+ *   tags={"Media"},
+ *   @OA\\RequestBody(
+ *     required=true,
+ *     @OA\\MediaType(
+ *       mediaType="application/octet-stream",
+ *       @OA\\Schema(
+ *         required={"content"},
+ *         @OA\\Property(
+ *           description="Binary content of file",
+ *           property="content",
+ *           type="string",
+ *           format="binary"
+ *         )
+ *       )
+ *     )
+ *   ),
+ *   @OA\\Response(
+ *     response=200, description="Success",
+ *     @OA\\Schema(type="string")
+ *   ),
+ *   @OA\\Response(
+ *     response=400, description="Bad Request"
+ *   )
+ * )
+ */
+

Set the XML root name

The OA\\Xml annotation may be used to set the XML root element for a given @OA\\XmlContent response body

/**
+ * @OA\\Schema(
+ *     schema="Error",
+ *     @OA\\Property(property="message"),
+ *     @OA\\Xml(name="details")
+ * )
+ */
+
+/**
+ * @OA\\Post(
+ *     path="/foobar",
+ *     @OA\\Response(
+ *         response=400,
+ *         description="Request error",
+ *         @OA\\XmlContent(ref="#/components/schemas/Error",
+ *           @OA\\Xml(name="error")
+ *        )
+ *     )
+ * )
+ */
+

upload multipart/form-data

Form posts are @OA\\Post requests with a multipart/form-data @OA\\RequestBody. The relevant bit looks something like this

/**
+ * @OA\\Post(
+ *   path="/v1/user/update",
+ *   summary="Form post",
+ *   @OA\\RequestBody(
+ *     @OA\\MediaType(
+ *       mediaType="multipart/form-data",
+ *       @OA\\Schema(
+ *         @OA\\Property(property="name"),
+ *         @OA\\Property(
+ *           description="file to upload",
+ *           property="avatar",
+ *           type="string",
+ *           format="binary",
+ *         ),
+ *       )
+ *     )
+ *   ),
+ *   @OA\\Response(response=200, description="Success")
+ * )
+ */
+

Default security scheme for all endpoints

Unless specified each endpoint needs to declare what security schemes it supports. However, there is a way to also configure security schemes globally for the whole API.

This is done on the @OA\\OpenApi annotations:

`,32),d=n("div",{class:"language-php"},[n("pre",null,[n("code",null,[n("span",{class:"token php language-php"},[n("span",{class:"token delimiter important"},""),s(),n("span",{class:"token punctuation"},"["),n("span",{class:"token punctuation"},"]"),n("span",{class:"token punctuation"},"]"),n("span",{class:"token punctuation"},"]"),s(` +`),n("span",{class:"token punctuation"},")")]),n("span",{class:"token delimiter punctuation"},"]")]),s(` +`),n("span",{class:"token attribute"},[n("span",{class:"token delimiter punctuation"},"#["),n("span",{class:"token attribute-content"},[n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[s("OAT"),n("span",{class:"token punctuation"},"\\"),s("Components")]),n("span",{class:"token punctuation"},"("),s(` + `),n("span",{class:"token attribute-class-name class-name"},"securitySchemes"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token punctuation"},"["),s(` + `),n("span",{class:"token attribute-class-name class-name"},"new"),s(),n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[s("OAT"),n("span",{class:"token punctuation"},"\\"),s("SecurityScheme")]),n("span",{class:"token punctuation"},"("),s(` + `),n("span",{class:"token attribute-class-name class-name"},"securityScheme"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string single-quoted-string"},"'bearerAuth'"),n("span",{class:"token punctuation"},","),s(` + `),n("span",{class:"token attribute-class-name class-name"},"type"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string single-quoted-string"},"'http'"),n("span",{class:"token punctuation"},","),s(` + `),n("span",{class:"token attribute-class-name class-name"},"scheme"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string single-quoted-string"},"'bearer'"),s(` + `),n("span",{class:"token punctuation"},")"),s(` + `),n("span",{class:"token punctuation"},"]"),s(` +`),n("span",{class:"token punctuation"},")")]),n("span",{class:"token delimiter punctuation"},"]")]),s(` +`),n("span",{class:"token keyword"},"class"),s(),n("span",{class:"token class-name-definition class-name"},"OpenApiSpec"),s(` +`),n("span",{class:"token punctuation"},"{"),s(` +`),n("span",{class:"token punctuation"},"}"),s(` +`)])])])],-1),m=e(`

Nested objects

Complex, nested data structures are defined by nesting @OA\\Property annotations inside others (with type="object").

/**
+ *  @OA\\Schema(
+ *    schema="Profile",
+ *    type="object",
+*
+ *    @OA\\Property(
+ *      property="Status",
+ *      type="string",
+ *      example="0"
+ *    ),
+ *
+ *    @OA\\Property(
+ *      property="Group",
+ *      type="object",
+ *
+ *      @OA\\Property(
+ *        property="ID",
+ *        description="ID de grupo",
+ *        type="number",
+ *        example=-1
+ *      ),
+ *
+ *      @OA\\Property(
+ *        property="Name",
+ *        description="Nombre de grupo",
+ *        type="string",
+ *        example="Superadmin"
+ *      )
+ *    )
+ *  )
+ */
+
+

Documenting union type response data using oneOf

A response with either a single or a list of QualificationHolder's.

/**
+ * @OA\\Response(
+ *     response=200,
+ *     @OA\\JsonContent(
+ *         oneOf={
+ *             @OA\\Schema(ref="#/components/schemas/QualificationHolder"),
+ *             @OA\\Schema(
+ *                 type="array",
+ *                 @OA\\Items(ref="#/components/schemas/QualificationHolder")
+ *             )
+ *         }
+ *     )
+ * )
+ */
+

Reusing responses

Global responses are found under /components/responses and can be referenced/shared just like schema definitions (models)

/**
+ * @OA\\Response(
+ *   response="product",
+ *   description="All information about a product",
+ *   @OA\\JsonContent(ref="#/components/schemas/Product")
+ * )
+ */
+class ProductResponse {}
+
+ // ...
+
+class ProductController
+{
+    /**
+     * @OA\\Get(
+     *   tags={"Products"},
+     *   path="/products/{product_id}",
+     *   @OA\\Response(
+     *       response="default",
+     *       ref="#/components/responses/product"
+     *   )
+     * )
+     */
+    public function getProduct($id)
+    {
+    }
+}
+

\`response\` parameter is always required

Even if referencing a shared response definition, the response parameter is still required.

mediaType="/"

Using */* as mediaType is not possible using annotations.

Example:

/**
+ * @OA\\MediaType(
+ *     mediaType="*/*",
+ *     @OA\\Schema(type="string",format="binary")
+ * )
+ */
+

The doctrine annotations library used for parsing annotations does not handle this and will interpret the */ bit as the end of the comment.

Using just * or application/octet-stream might be usable workarounds.

Warning about Multiple response with same response="200"

There are two scenarios where this can happen

  1. A single endpoint contains two responses with the same response value.
  2. There are multiple global response declared, again more than one with the same response value.

Callbacks

The API does include basic support for callbacks. However, this needs to be set up mostly manually.

Example

/**
+ *     ...
+ *
+ *     callbacks={
+ *         "onChange"={
+ *              "{$request.query.callbackUrl}"={
+ *                  "post": {
+ *                      "requestBody": @OA\\RequestBody(
+ *                          description="subscription payload",
+ *                          @OA\\MediaType(mediaType="application/json", @OA\\Schema(
+ *                              @OA\\Property(property="timestamp", type="string", format="date-time", description="time of change")
+ *                          ))
+ *                      )
+ *                  },
+ *                  "responses": {
+ *                      "202": {
+ *                          "description": "Your server implementation should return this HTTP status code if the data was received successfully"
+ *                      }
+ *                  }
+ *              }
+ *         }
+ *     }
+ *
+ *     ...
+ *
+ */
+

(Mostly) virtual models

Typically, a model is annotated by adding a @OA\\Schema annotation to the class and then individual @OA\\Property annotations to the individually declared class properties.

It is possible, however, to nest O@\\Property annotations inside a schema even without properties. In fact, all that is needed is a code anchor - e.g. an empty class.

use OpenApi\\Attributes as OA;
+
+#[OA\\Schema(
+    properties: [
+        'name' => new OA\\Property(property: 'name', type: 'string'),
+        'email' => new OA\\Property(property: 'email', type: 'string'),
+    ]
+)]
+class User {}
+

Using class name as type instead of references

Typically, when referencing schemas this is done using $ref's

#[OAT\\Schema(schema: 'user')]
+class User
+{
+}
+
+#[OAT\\Schema()]
+class Book
+{
+    /**
+     * @var User
+     */
+    #[OAT\\Property(ref: '#/components/schemas/user')]
+    public $author;
+}
+

This works, but is not very convenient.

First, when using custom schema names (schema: 'user'), this needs to be taken into account everywhere. Secondly, having to write ref: '#/components/schemas/user' is tedious and error-prone.

Using attributes all this changes as we can take advantage of PHP itself by referring to a schema by its (fully qualified) class name.

With the same User schema as before, the Book::author property could be written in a few different ways

    #[OAT\\Property()]
+    public User author;
+

or

    /**
+     * @var User
+     */
+    #[OAT\\Property()]
+    public author;
+

or

    #[OAT\\Property(type: User::class)]
+    public author;
+

Enums

As of PHP 8.1 there is native support for enum's.

swagger-php supports enums in much the same way as class names can be used to reference schemas.

Example

#[Schema()]
+enum State
+{
+    case OPEN;
+    case MERGED;
+    case DECLINED;
+}
+
+#[Schema()]
+class PullRequest
+   #[OAT\\Property()]
+   public State $state
+}
+

However, in this case the schema generated for State will be an enum:

components:
+  schemas:
+    PullRequest:
+      properties:
+        state:
+          $ref: '#/components/schemas/State'
+      type: object
+    State:
+      type: string
+      enum:
+        - OPEN
+        - MERGED
+        - DECLINED
+

Multi value query parameter: &q[]=1&q[]=1

PHP allows to have query parameters multiple times in the url and will combine the values to an array if the parameter name uses trailing []. In fact, it is possible to create nested arrays too by using more than one pair of [].

In terms of OpenAPI, the parameters can be considered a single parameter with a list of values.

/**
+ * @OA\\Get(
+ *     path="/api/endpoint",
+ *     description="The endpoint",
+ *     operationId="endpoint",
+ *     tags={"endpoints"},
+ *     @OA\\Parameter(
+ *         name="things[]",
+ *         in="query",
+ *         description="A list of things.",
+ *         required=false,
+ *         @OA\\Schema(
+ *             type="array",
+ *             @OA\\Items(type="integer")
+ *         )
+ *     ),
+ *     @OA\\Response(response="200", description="All good")
+ * )
+ */
+

The corresponding bit of the spec will look like this:

      parameters:
+        -
+          name: 'things[]'
+          in: query
+          description: 'A list of things.'
+          required: false
+          schema:
+            type: array
+            items:
+              type: integer
+

swagger-ui will show a form that allows to add/remove items (integer values in this case) to/from a list and post those values as something like ?things[]=1&things[]=2&things[]=0

Custom response classes

Even with using refs there is a bit of overhead in sharing responses. One way around that is to write your own response classes. The beauty is that in your custom __construct() method you can prefill as much as you need.

Best of all, this works for both annotations and attributes.

Example:

use OpenApi\\Attributes as OA;
+
+/**
+ * @Annotation
+ */
+#[\\Attribute(\\Attribute::TARGET_CLASS | \\Attribute::TARGET_METHOD | \\Attribute::IS_REPEATABLE)]
+class BadRequest extends OA\\Response
+{
+    public function __construct()
+    {
+        parent::__construct(response: 400, description: 'Bad request');
+    }
+}
+
+class Controller
+{
+
+    #[OA\\Get(path: '/foo', responses: [new BadRequest()])]
+    public function get()
+    {
+    }
+
+    #[OA\\Post(path: '/foo')]
+    #[BadRequest]
+    public function post()
+    {
+    }
+
+    /**
+     * @OA\\Delete(
+     *     path="/foo",
+     *     @BadRequest()
+     * )
+     */
+    public function delete()
+    {
+    }
+}
+

Annotations only?

If you are only interested in annotations you canleave out the attribute setup line (#[\\Attribute...) for BadRequest.

Furthermore, your custom annotations should extend from the OpenApi\\Annotations namespace.

Annotating class constants 

use OpenApi\\Attributes as OA;
+
+#[OA\\Schema()]
+class Airport
+{
+    #[OA\\Property(property='kind')]
+    public const KIND = 'Airport';
+}
+

The const property is supported in OpenApi 3.1.0.

components:
+  schemas:
+    Airport:
+        properties:
+          kind:
+            type: string
+            const: Airport
+

For 3.0.0 this is serialized into a single value enum.

components:
+  schemas:
+    Airport:
+        properties:
+          kind:
+            type: string
+            enum:
+              - Airport
+
`,65);function h(y,q,g,f,b,A){const t=u("codeblock");return l(),p("div",null,[r,c(t,{id:"minimal"},{an:a(()=>[d]),at:a(()=>[k]),_:1}),m])}var w=o(i,[["render",h]]);export{O as __pageData,w as default}; diff --git a/assets/guide_cookbook.md.58253880.lean.js b/assets/guide_cookbook.md.58253880.lean.js new file mode 100644 index 000000000..ecfe6c45b --- /dev/null +++ b/assets/guide_cookbook.md.58253880.lean.js @@ -0,0 +1,38 @@ +import{_ as o,c as p,b as c,w as a,a as e,r as u,o as l,d as n,e as s}from"./app.d3800f98.js";const O='{"title":"Cookbook","description":"","frontmatter":{},"headers":[{"level":2,"title":"x-tagGroups","slug":"x-taggroups"},{"level":2,"title":"Adding examples to @OA\\\\Response","slug":"adding-examples-to-oa-response"},{"level":2,"title":"External documentation","slug":"external-documentation"},{"level":2,"title":"Properties with union types","slug":"properties-with-union-types"},{"level":2,"title":"Referencing a security scheme","slug":"referencing-a-security-scheme"},{"level":2,"title":"File upload with headers","slug":"file-upload-with-headers"},{"level":2,"title":"Set the XML root name","slug":"set-the-xml-root-name"},{"level":2,"title":"upload multipart/form-data","slug":"upload-multipart-form-data"},{"level":2,"title":"Default security scheme for all endpoints","slug":"default-security-scheme-for-all-endpoints"},{"level":2,"title":"Nested objects","slug":"nested-objects"},{"level":2,"title":"Documenting union type response data using oneOf","slug":"documenting-union-type-response-data-using-oneof"},{"level":2,"title":"Reusing responses","slug":"reusing-responses"},{"level":2,"title":"mediaType=\\"/\\"","slug":"mediatype"},{"level":2,"title":"Warning about Multiple response with same response=\\"200\\"","slug":"warning-about-multiple-response-with-same-response-200"},{"level":2,"title":"Callbacks","slug":"callbacks"},{"level":2,"title":"(Mostly) virtual models","slug":"mostly-virtual-models"},{"level":2,"title":"Using class name as type instead of references","slug":"using-class-name-as-type-instead-of-references"},{"level":2,"title":"Enums","slug":"enums"},{"level":2,"title":"Multi value query parameter: &q[]=1&q[]=1","slug":"multi-value-query-parameter-q-1-q-1"},{"level":2,"title":"Custom response classes","slug":"custom-response-classes"},{"level":2,"title":"Annotating class constants","slug":"annotating-class-constants"}],"relativePath":"guide/cookbook.md"}',i={},r=e("",32),d=n("div",{class:"language-php"},[n("pre",null,[n("code",null,[n("span",{class:"token php language-php"},[n("span",{class:"token delimiter important"},""),s(),n("span",{class:"token punctuation"},"["),n("span",{class:"token punctuation"},"]"),n("span",{class:"token punctuation"},"]"),n("span",{class:"token punctuation"},"]"),s(` +`),n("span",{class:"token punctuation"},")")]),n("span",{class:"token delimiter punctuation"},"]")]),s(` +`),n("span",{class:"token attribute"},[n("span",{class:"token delimiter punctuation"},"#["),n("span",{class:"token attribute-content"},[n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[s("OAT"),n("span",{class:"token punctuation"},"\\"),s("Components")]),n("span",{class:"token punctuation"},"("),s(` + `),n("span",{class:"token attribute-class-name class-name"},"securitySchemes"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token punctuation"},"["),s(` + `),n("span",{class:"token attribute-class-name class-name"},"new"),s(),n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[s("OAT"),n("span",{class:"token punctuation"},"\\"),s("SecurityScheme")]),n("span",{class:"token punctuation"},"("),s(` + `),n("span",{class:"token attribute-class-name class-name"},"securityScheme"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string single-quoted-string"},"'bearerAuth'"),n("span",{class:"token punctuation"},","),s(` + `),n("span",{class:"token attribute-class-name class-name"},"type"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string single-quoted-string"},"'http'"),n("span",{class:"token punctuation"},","),s(` + `),n("span",{class:"token attribute-class-name class-name"},"scheme"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string single-quoted-string"},"'bearer'"),s(` + `),n("span",{class:"token punctuation"},")"),s(` + `),n("span",{class:"token punctuation"},"]"),s(` +`),n("span",{class:"token punctuation"},")")]),n("span",{class:"token delimiter punctuation"},"]")]),s(` +`),n("span",{class:"token keyword"},"class"),s(),n("span",{class:"token class-name-definition class-name"},"OpenApiSpec"),s(` +`),n("span",{class:"token punctuation"},"{"),s(` +`),n("span",{class:"token punctuation"},"}"),s(` +`)])])])],-1),m=e("",65);function h(y,q,g,f,b,A){const t=u("codeblock");return l(),p("div",null,[r,c(t,{id:"minimal"},{an:a(()=>[d]),at:a(()=>[k]),_:1}),m])}var w=o(i,[["render",h]]);export{O as __pageData,w as default}; diff --git a/assets/guide_faq.md.818b1e6e.js b/assets/guide_faq.md.818b1e6e.js new file mode 100644 index 000000000..ad5e97805 --- /dev/null +++ b/assets/guide_faq.md.818b1e6e.js @@ -0,0 +1,88 @@ +import{_ as n,c as e,o as a,a as s}from"./app.d3800f98.js";const k='{"title":"FAQ","description":"","frontmatter":{},"headers":[{"level":2,"title":"Warning: Required @OA\\\\Info() not found","slug":"warning-required-oa-info-not-found"},{"level":2,"title":"Annotations missing","slug":"annotations-missing"},{"level":2,"title":"Skipping unknown \\\\SomeClass","slug":"skipping-unknown-someclass"},{"level":3,"title":"Using the -b --bootstrap option","slug":"using-the-b-bootstrap-option"},{"level":3,"title":"Namespace mismatch","slug":"namespace-mismatch"},{"level":2,"title":"No output from openapi command line tool","slug":"no-output-from-openapi-command-line-tool"}],"relativePath":"guide/faq.md"}',t={},o=s(`

FAQ

Warning: Required @OA\\Info() not found

With adding support for PHP attributes in version 4, some architectural changes had to be made.

One of those changes is that placing annotations in your source files is now subject to the same limitations as attributes. These limits are dictated by the PHP reflection API, specifically where it provides access to attributes and doc comments.

This means stand-alone annotations are no longer supported and ignored as swagger-php cannot "see" them any more.

Supported locations:

  • class
  • interface
  • trait
  • method
  • property
  • class/interface const

Most commonly this manifests with a warning about the required @OA\\Info not being found. While most annotations have specific related code, the info annotation (and a few more) is kind of global.

The simplest solution to avoid this issue is to add a 'dummy' class to the docblock and add all 'global' annotations (e.g. Tag, Server, SecurityScheme, etc.) in a single docblock to that class.

/**
+ * @OA\\Tag(
+ *     name="user",
+ *     description="User related operations"
+ * )
+ * @OA\\Info(
+ *     version="1.0",
+ *     title="Example API",
+ *     description="Example info",
+ *     @OA\\Contact(name="Swagger API Team")
+ * )
+ * @OA\\Server(
+ *     url="https://example.localhost",
+ *     description="API server"
+ * )
+ */
+class OpenApiSpec
+{
+}
+

As of version 4.8 the doctrine/annotations library is optional and might cause the same message.

If this is the case, doctrine annotations must be installed separately:

composer require doctrine/annotations
+

Annotations missing

Another side effect of using reflection is that swagger-php "can't see" multiple consecutive docblocks any more as the PHP reflection API only provides access to the docblock closest to a given structural element.

class Controller
+{
+    /**
+     * @OA\\Delete(
+     *      path="/api/v0.0.2/notifications/{id}",
+     *      operationId="deleteNotificationById",
+     *      summary="Delete notification by ID",
+     *      @OA\\Parameter(name="id", in="path", @OA\\Schema(type="integer")),
+     *      @OA\\Response(response=200, description="OK"),
+     *      @OA\\Response(response=400, description="Bad Request")
+     * )
+     */
+    /**
+     * Delete notification by ID.
+     *
+     * @param Request $request
+     * @param AppNotification $notification
+     *
+     * @return Response
+     * @throws Exception
+     */
+    public function destroy(Request $request, AppNotification $notification) {
+        //
+    }
+}
+

In this case the simplest solution is to merge both docblocks. As an additional benefit the duplication of the summary can be avoided.

In this improved version swagger-php will automatically use the docblock summary just as explicitly done above.

class Controller
+{
+    /**
+     * Delete notification by ID.
+     *
+     * @OA\\Delete(
+     *      path="/api/v0.0.2/notifications/{id}",
+     *      operationId="deleteNotificationById",
+     *      @OA\\Parameter(name="id", in="path", @OA\\Schema(type="integer")),
+     *      @OA\\Response(response=200, description="OK"),
+     *      @OA\\Response(response=400, description="Bad Request")
+     * )
+     *
+     * @param Request $request
+     * @param AppNotification $notification
+     *
+     * @return Response
+     * @throws Exception
+     */
+    public function destroy(Request $request, AppNotification $notification) {
+        //
+    }
+}
+

Resulting spec:

openapi: 3.0.0
+paths:
+  '/api/v0.0.2/notifications/{id}':
+    delete:
+      summary: 'XDelete notification by ID.'
+      operationId: deleteNotificationById
+      parameters:
+        -
+          name: id
+          in: path
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: OK
+        '400':
+          description: 'Bad Request'
+
+

Skipping unknown \\SomeClass

This message means that swagger-php has tried to use reflection to inspect \\SomeClass and that PHP could not find/load that class. Effectively, this means that class_exists("\\SomeClass") returns false.

Using the -b --bootstrap option

There are a number of reasons why this could happen. If you are using the openapi command line tool from a global installation typically the application classloader (composer) is not active. With you application root being myapp you could try:

openapi -b myapp/vendor/autoload.php myapp/src
+

The -b allows to execute some extra PHP code to load whatever is needed to register your apps classloader with PHP.

Namespace mismatch

Another reason for this error could be that your class actually has the wrong namespace (or no namespace at all!).

Depending on your framework this might still work in the context of your app, but the composer autoloader alone might not be able to load your class (assuming you are using composer).

No output from openapi command line tool

Depending on your PHP configuration, running the openapi command line tool might result in no output at all.

The reason for this is that openapi currently uses the error_log function for all output.

So if this is configured to write to a file, then it will seem like the command is broken.

`,34),i=[o];function p(c,l,r,u,d,h){return a(),e("div",null,i)}var f=n(t,[["render",p]]);export{k as __pageData,f as default}; diff --git a/assets/guide_faq.md.818b1e6e.lean.js b/assets/guide_faq.md.818b1e6e.lean.js new file mode 100644 index 000000000..1cb883a32 --- /dev/null +++ b/assets/guide_faq.md.818b1e6e.lean.js @@ -0,0 +1 @@ +import{_ as n,c as e,o as a,a as s}from"./app.d3800f98.js";const k='{"title":"FAQ","description":"","frontmatter":{},"headers":[{"level":2,"title":"Warning: Required @OA\\\\Info() not found","slug":"warning-required-oa-info-not-found"},{"level":2,"title":"Annotations missing","slug":"annotations-missing"},{"level":2,"title":"Skipping unknown \\\\SomeClass","slug":"skipping-unknown-someclass"},{"level":3,"title":"Using the -b --bootstrap option","slug":"using-the-b-bootstrap-option"},{"level":3,"title":"Namespace mismatch","slug":"namespace-mismatch"},{"level":2,"title":"No output from openapi command line tool","slug":"no-output-from-openapi-command-line-tool"}],"relativePath":"guide/faq.md"}',t={},o=s("",34),i=[o];function p(c,l,r,u,d,h){return a(),e("div",null,i)}var f=n(t,[["render",p]]);export{k as __pageData,f as default}; diff --git a/assets/guide_generating-openapi-documents.md.4e871b91.js b/assets/guide_generating-openapi-documents.md.4e871b91.js new file mode 100644 index 000000000..d452ad442 --- /dev/null +++ b/assets/guide_generating-openapi-documents.md.4e871b91.js @@ -0,0 +1,30 @@ +import{_ as a,c as n,o as s,a as e}from"./app.d3800f98.js";const m='{"title":"Generating OpenAPI documents","description":"","frontmatter":{},"headers":[{"level":2,"title":"./bin/openapi","slug":"bin-openapi"},{"level":2,"title":"Using PHP","slug":"using-php"}],"relativePath":"guide/generating-openapi-documents.md"}',t={},p=e(`

Generating OpenAPI documents

./bin/openapi

swagger-php includes a command line tool ./bin/openapi. This can be used to generate OpenAPI documents.

> ./vendor/bin/openapi app -o openapi.yaml
+

Output Format

By default the output format is YAML. If a filename is given (via --output or -o) the tool will use the file extension to determine the format.

The --format option can be used to force a specific format.

For a list of all available options use the -h option

> ./bin/openapi -h
+
+Usage: openapi [--option value] [/path/to/project ...]
+
+Options:
+  --config (-c)     Generator config
+                    ex: -c operationId.hash=false
+  --legacy (-l)     Use legacy TokenAnalyser; default is the new ReflectionAnalyser
+  --output (-o)     Path to store the generated documentation.
+                    ex: --output openapi.yaml
+  --exclude (-e)    Exclude path(s).
+                    ex: --exclude vendor,library/Zend
+  --pattern (-n)    Pattern of files to scan.
+                    ex: --pattern "*.php" or --pattern "/\\.(phps|php)$/"
+  --bootstrap (-b)  Bootstrap a php file for defining constants, etc.
+                    ex: --bootstrap config/constants.php
+  --processor (-p)  Register an additional processor.
+  --format (-f)     Force yaml or json.
+  --debug (-d)      Show additional error information.
+  --version         The OpenAPI version; defaults to 3.0.0.
+  --help (-h)       Display this help message.
+

Using PHP

Depending on your use case PHP code can also be used to generate OpenAPI documents in a more dynamic way.

In its simplest form this may look something like

<?php
+require("vendor/autoload.php");
+
+$openapi = \\OpenApi\\Generator::scan(['/path/to/project']);
+
+header('Content-Type: application/x-yaml');
+echo $openapi->toYaml();
+

Programming API

Details about the swagger-php API can be found in the reference.

`,12),o=[p];function c(i,l,r,u,d,k){return s(),n("div",null,o)}var g=a(t,[["render",c]]);export{m as __pageData,g as default}; diff --git a/assets/guide_generating-openapi-documents.md.4e871b91.lean.js b/assets/guide_generating-openapi-documents.md.4e871b91.lean.js new file mode 100644 index 000000000..a28240d41 --- /dev/null +++ b/assets/guide_generating-openapi-documents.md.4e871b91.lean.js @@ -0,0 +1 @@ +import{_ as a,c as n,o as s,a as e}from"./app.d3800f98.js";const m='{"title":"Generating OpenAPI documents","description":"","frontmatter":{},"headers":[{"level":2,"title":"./bin/openapi","slug":"bin-openapi"},{"level":2,"title":"Using PHP","slug":"using-php"}],"relativePath":"guide/generating-openapi-documents.md"}',t={},p=e("",12),o=[p];function c(i,l,r,u,d,k){return s(),n("div",null,o)}var g=a(t,[["render",c]]);export{m as __pageData,g as default}; diff --git a/assets/guide_index.md.2455f0b6.js b/assets/guide_index.md.2455f0b6.js new file mode 100644 index 000000000..84dfcc8bb --- /dev/null +++ b/assets/guide_index.md.2455f0b6.js @@ -0,0 +1 @@ +import{_ as e,c as t,o as a,a as o}from"./app.d3800f98.js";const m='{"title":"What is Swagger-PHP?","description":"","frontmatter":{},"headers":[],"relativePath":"guide/index.md"}',n={},s=o('

What is Swagger-PHP?

swagger-php is a library that extracts API metadata from your PHP source code files.

The idea is to add swagger-php annotations or attributes next to the relevant PHP code in your application. These will contain the details about your API and swagger-php will convert those into machine-readable OpenAPI documentation.

By adding your API documentation next to the corresponding source code (same file!) makes it easy to keep it up-to-date as all details can be modified in one place.

Annotating vs. Annotations

When talking about annotating your code we mean the act of adding meta-data to your codebase. This can be done by either adding Annotations or Attributes.

Requirements

Using swagger-php requires a minimum of PHP\xA07.2 for using annotations and at least PHP\xA08.1 to use attributes.

',6),i=[s];function r(c,d,p,h,l,g){return a(),t("div",null,i)}var _=e(n,[["render",r]]);export{m as __pageData,_ as default}; diff --git a/assets/guide_index.md.2455f0b6.lean.js b/assets/guide_index.md.2455f0b6.lean.js new file mode 100644 index 000000000..89cc90d13 --- /dev/null +++ b/assets/guide_index.md.2455f0b6.lean.js @@ -0,0 +1 @@ +import{_ as e,c as t,o as a,a as o}from"./app.d3800f98.js";const m='{"title":"What is Swagger-PHP?","description":"","frontmatter":{},"headers":[],"relativePath":"guide/index.md"}',n={},s=o("",6),i=[s];function r(c,d,p,h,l,g){return a(),t("div",null,i)}var _=e(n,[["render",r]]);export{m as __pageData,_ as default}; diff --git a/assets/guide_installation.md.c1a9b9e5.js b/assets/guide_installation.md.c1a9b9e5.js new file mode 100644 index 000000000..d2dad67da --- /dev/null +++ b/assets/guide_installation.md.c1a9b9e5.js @@ -0,0 +1,3 @@ +import{_ as e,c as a,o,a as t}from"./app.d3800f98.js";const u='{"title":"Installation","description":"","frontmatter":{},"headers":[{"level":2,"title":"Per project","slug":"per-project"},{"level":2,"title":"Globally","slug":"globally"}],"relativePath":"guide/installation.md"}',r={},l=t(`

Installation

Per project

We recommend adding swagger-php to your project using Composer

> composer require zircote/swagger-php
+

Globally

Alternatively, use the composer global argument to install swagger-php globally.

> composer global require zircote/swagger-php
+

PATH variables

Remember to add the ~/.composer/vendor/bin directory to the PATH in your environment.

`,8),s=[l];function n(c,i,p,d,h,g){return o(),a("div",null,s)}var m=e(r,[["render",n]]);export{u as __pageData,m as default}; diff --git a/assets/guide_installation.md.c1a9b9e5.lean.js b/assets/guide_installation.md.c1a9b9e5.lean.js new file mode 100644 index 000000000..21c38b25f --- /dev/null +++ b/assets/guide_installation.md.c1a9b9e5.lean.js @@ -0,0 +1 @@ +import{_ as e,c as a,o,a as t}from"./app.d3800f98.js";const u='{"title":"Installation","description":"","frontmatter":{},"headers":[{"level":2,"title":"Per project","slug":"per-project"},{"level":2,"title":"Globally","slug":"globally"}],"relativePath":"guide/installation.md"}',r={},l=t("",8),s=[l];function n(c,i,p,d,h,g){return o(),a("div",null,s)}var m=e(r,[["render",n]]);export{u as __pageData,m as default}; diff --git a/assets/guide_migrating-to-v3.md.f8a7ce6f.js b/assets/guide_migrating-to-v3.md.f8a7ce6f.js new file mode 100644 index 000000000..fccddf624 --- /dev/null +++ b/assets/guide_migrating-to-v3.md.f8a7ce6f.js @@ -0,0 +1 @@ +import{_ as e,c as a,o as t,a as o}from"./app.d3800f98.js";const u='{"title":"Migrating to v3","description":"","frontmatter":{},"headers":[{"level":2,"title":"The default output changed from json to yaml","slug":"the-default-output-changed-from-json-to-yaml"},{"level":2,"title":"Updated CLI","slug":"updated-cli"},{"level":2,"title":"Changed annotations","slug":"changed-annotations"},{"level":3,"title":"SWG is renamed to OA","slug":"swg-is-renamed-to-oa"},{"level":3,"title":"@SWG\\\\Swagger() is renamed to @OA\\\\OpenApi()","slug":"swg-swagger-is-renamed-to-oa-openapi"},{"level":3,"title":"@SWG\\\\Path() is renamed to @OA\\\\PathItem()","slug":"swg-path-is-renamed-to-oa-pathitem"},{"level":3,"title":"@SWG\\\\Definition() is removed","slug":"swg-definition-is-removed"},{"level":3,"title":"@SWG\\\\Path is removed","slug":"swg-path-is-removed"},{"level":3,"title":"Consumes, produces field is removed from OpenAPI specification","slug":"consumes-produces-field-is-removed-from-openapi-specification"},{"level":3,"title":"Rename parameter references","slug":"rename-parameter-references"},{"level":3,"title":"Rename response references","slug":"rename-response-references"},{"level":3,"title":"Renamed cli","slug":"renamed-cli"},{"level":3,"title":"More details about differences:","slug":"more-details-about-differences"}],"relativePath":"guide/migrating-to-v3.md"}',r={},i=o('

Migrating to v3

Swagger-PHP 3.x generates an openapi.json file that follows the OpenAPI Version 3.0.x Specification.

If you need to output the older 2.x specification use OpenApi-php 2.x

The default output changed from json to yaml

This aligns better with the direction of the swagger documentation and examples. Annotations can't be used as string anymore, you'll need to call toYaml() or toJson() if you prefer the json format.

Updated CLI

  • Added colors
  • No output for successful execution (Removed summary)
  • non-zero exit when an error occurred.
  • Defaults to yaml
  • Defaults to stdout. To save to openapi.yaml use -o or >

Changed annotations

SWG is renamed to OA

The namespace is renamed from SWG (Swagger) to OA (OpenApi)

@SWG\\Swagger() is renamed to @OA\\OpenApi()

@SWG\\Path() is renamed to @OA\\PathItem()

The specification uses the term "Path Item Object", updated the annotation to reflect that.

@SWG\\Definition() is removed

Use @OA\\Schema() instead of @OA\\Definition() and update the references from "#/definitions/something" to "#/components/schemas/something".

@SWG\\Path is removed

Use @OA\\PathItem instead of @SWG\\Path and update references.

Consumes, produces field is removed from OpenAPI specification

Use @OA\\MediaType to set data format.

Rename parameter references

Rename #/parameters/{parameter_name} to #/components/parameters/{parameter_name}

Rename response references

Rename #/responses/{response} to #/components/responses/{response}

Renamed cli

Renamed swagger to openapi

More details about differences:

A Visual Guide to What's New in Swagger 3.0

',27),n=[i];function s(d,h,l,c,p,m){return t(),a("div",null,n)}var g=e(r,[["render",s]]);export{u as __pageData,g as default}; diff --git a/assets/guide_migrating-to-v3.md.f8a7ce6f.lean.js b/assets/guide_migrating-to-v3.md.f8a7ce6f.lean.js new file mode 100644 index 000000000..641fde572 --- /dev/null +++ b/assets/guide_migrating-to-v3.md.f8a7ce6f.lean.js @@ -0,0 +1 @@ +import{_ as e,c as a,o as t,a as o}from"./app.d3800f98.js";const u='{"title":"Migrating to v3","description":"","frontmatter":{},"headers":[{"level":2,"title":"The default output changed from json to yaml","slug":"the-default-output-changed-from-json-to-yaml"},{"level":2,"title":"Updated CLI","slug":"updated-cli"},{"level":2,"title":"Changed annotations","slug":"changed-annotations"},{"level":3,"title":"SWG is renamed to OA","slug":"swg-is-renamed-to-oa"},{"level":3,"title":"@SWG\\\\Swagger() is renamed to @OA\\\\OpenApi()","slug":"swg-swagger-is-renamed-to-oa-openapi"},{"level":3,"title":"@SWG\\\\Path() is renamed to @OA\\\\PathItem()","slug":"swg-path-is-renamed-to-oa-pathitem"},{"level":3,"title":"@SWG\\\\Definition() is removed","slug":"swg-definition-is-removed"},{"level":3,"title":"@SWG\\\\Path is removed","slug":"swg-path-is-removed"},{"level":3,"title":"Consumes, produces field is removed from OpenAPI specification","slug":"consumes-produces-field-is-removed-from-openapi-specification"},{"level":3,"title":"Rename parameter references","slug":"rename-parameter-references"},{"level":3,"title":"Rename response references","slug":"rename-response-references"},{"level":3,"title":"Renamed cli","slug":"renamed-cli"},{"level":3,"title":"More details about differences:","slug":"more-details-about-differences"}],"relativePath":"guide/migrating-to-v3.md"}',r={},i=o("",27),n=[i];function s(d,h,l,c,p,m){return t(),a("div",null,n)}var g=e(r,[["render",s]]);export{u as __pageData,g as default}; diff --git a/assets/guide_migrating-to-v4.md.5a3b1acb.js b/assets/guide_migrating-to-v4.md.5a3b1acb.js new file mode 100644 index 000000000..465691ba0 --- /dev/null +++ b/assets/guide_migrating-to-v4.md.5a3b1acb.js @@ -0,0 +1,48 @@ +import{_ as a,c as n,o as s,a as e}from"./app.d3800f98.js";const m='{"title":"Migrating to v4","description":"","frontmatter":{},"headers":[{"level":2,"title":"Overview","slug":"overview"},{"level":2,"title":"Annotations as PHP attributes","slug":"annotations-as-php-attributes"},{"level":3,"title":"Using annotations","slug":"using-annotations"},{"level":3,"title":"Using attributes","slug":"using-attributes"},{"level":2,"title":"Optional nesting","slug":"optional-nesting"},{"level":2,"title":"Annotations must be associated with a structural element","slug":"annotations-must-be-associated-with-a-structural-element"},{"level":2,"title":"The PathParameter annotation","slug":"the-pathparameter-annotation"},{"level":2,"title":"The Attachable annotation","slug":"the-attachable-annotation"},{"level":2,"title":"Removed deprecated elements","slug":"removed-deprecated-elements"},{"level":3,"title":"\\\\Openapi\\\\Analysis::processors()","slug":"openapi-analysis-processors"},{"level":3,"title":"\\\\Openapi\\\\Analyser::$whitelist","slug":"openapi-analyser-whitelist"},{"level":3,"title":"\\\\Openapi\\\\Analyser::$defaultImports","slug":"openapi-analyser-defaultimports"},{"level":3,"title":"\\\\Openapi\\\\Logger","slug":"openapi-logger"},{"level":2,"title":"Improvements to the Generator class","slug":"improvements-to-the-generator-class"}],"relativePath":"guide/migrating-to-v4.md"}',t={},o=e(`

Migrating to v4

Overview

  • As of PHP 8.1 annotations may be used as PHP attributes instead. That means all references to annotations in this document also apply to attributes.
  • Annotations now must be associated with a structural element (class, trait, interface), a method, property or const.
  • A new annotation PathParameter was added for improved framework support.
  • A new annotation Attachable was added to simplify custom processing. Attachable can be used to attach arbitrary data to any given annotation.
  • Deprecated elements have been removed
    • \\Openapi\\Analysis::processors()
    • \\Openapi\\Analyser::$whitelist
    • \\Openapi\\Analyser::$defaultImports
    • \\Openapi\\Logger
  • Legacy support is available via the previous TokenAnalyser
  • Improvements to the Generator class

Annotations as PHP attributes

While PHP attributes have been around since PHP 8.0 they were lacking the ability to be nested. This changes with PHP 8.1 which allows to use new in initializers.

Swagger-php attributes also make use of named arguments, so attribute parameters can be (mostly) typed. There are some limitations to type hints which can only be resolved once support for PHP 7.x is dropped.

Using annotations 


+use OpenApi\\Annotations as OA;
+
+/**
+ * @OA\\Info(
+ *   version="1.0.0",
+ *   title="My API",
+ *   @OA\\License(name="MIT"),
+ *   @OA\\Attachable()
+ * )
+ */
+class OpenApiSpec
+{
+}
+

Using attributes 


+use OpenApi\\Attributes as OA;
+
+#[OA\\Info(
+    version: '1.0.0',
+    title: 'My API',
+    attachables: [new OA\\Attachable()]
+)]
+#[OA\\License(name: 'MIT')]
+class OpenApiSpec
+{
+}
+

Optional nesting

One of the few differences between annotations and attributes visible in the above example is that the OA\\License attribute is not nested within OA\\Info. Nesting of attributes is possible and required in certain cases however, in cases where there is no ambiguity attributes may be all written on the top level and swagger-php will do the rest.

Annotations must be associated with a structural element

The (now legacy) way of parsing PHP files meant that docblocks could live in a file without a single line of actual PHP code.

PHP Attributes cannot exist in isolation; they need code to be associated with and then are available via reflection on the associated structural element. In order to allow to keep supporting annotations and the code simple it made sense to treat annotations and attributes the same in this respect.

The PathParameter annotation

As annotation this is just a short form for

   @OA\\Parameter(in='body')
+

Things get more interesting when it comes to using it as attribute, though. In the context of a controller you can now do something like

class MyController
+{
+    #[OA\\Get(path: '/products/{product_id}')]
+    public function getProduct(
+        #[OA\\PathParameter] string $product_id)
+    {
+    }
+}
+

Here it avoids having to duplicate details about the $product_id parameter and the simple use of the attribute will pick up typehints automatically.

The Attachable annotation

Technically these were added in version 3.3.0, however they become really useful only with version 4.

The attachable annotation is similar to the OpenApi vendor extension x=. The main difference are that

  1. Attachables allow complex structures and strong typing
  2. Attachables are not added to the generated spec.

Their main purpose is to make customizing swagger-php easier by allowing to add arbitrary data to any annotation.

One possible use case could be custom annotations. Classes extending Attachable are allowed to limit the allowed parent annotations. This means it would be easy to create a new attribute to flag certain endpoints as private and exclude them under certain conditions from the spec (via a custom processor).

Removed deprecated elements

\\Openapi\\Analysis::processors()

Processors have been moved into the Generator class incl. some new convenience methods.

\\Openapi\\Analyser::$whitelist

This has been replaced with the Generator namespaces property.

\\Openapi\\Analyser::$defaultImports

This has been replaced with the Generator aliases property.

\\Openapi\\Logger

This class has been removed completely. Instead, you may configure a PSR-3 logger.

Improvements to the Generator class

The removal of deprecated static config options means that the Generator class now is the main entry point into swagger-php when used programmatically.

To make the migration as simple as possible a new Generator::withContext(callable) has been added. This allows to use parts of the library (an Analyser instance, for example) within the context of a Generator instance.

Example:

$analyser = createMyAnalyser();
+
+$analysis = (new Generator())
+    ->addAlias('fo', 'My\\\\Attribute\\\\Namespace')
+    ->addNamespace('Other\\\\Annotations\\\\')
+    ->withContext(function (Generator $generator, Analysis $analysis, Context $context) use ($analyser) {
+        $analyser->setGenerator($generator);
+        $analysis = $analyser->fromFile('my_code.php', $context);
+        $analysis->process($generator->getProcessors());
+
+        return $analysis;
+    });
+
`,41),p=[o];function i(c,l,r,u,d,h){return s(),n("div",null,p)}var g=a(t,[["render",i]]);export{m as __pageData,g as default}; diff --git a/assets/guide_migrating-to-v4.md.5a3b1acb.lean.js b/assets/guide_migrating-to-v4.md.5a3b1acb.lean.js new file mode 100644 index 000000000..659e77809 --- /dev/null +++ b/assets/guide_migrating-to-v4.md.5a3b1acb.lean.js @@ -0,0 +1 @@ +import{_ as a,c as n,o as s,a as e}from"./app.d3800f98.js";const m='{"title":"Migrating to v4","description":"","frontmatter":{},"headers":[{"level":2,"title":"Overview","slug":"overview"},{"level":2,"title":"Annotations as PHP attributes","slug":"annotations-as-php-attributes"},{"level":3,"title":"Using annotations","slug":"using-annotations"},{"level":3,"title":"Using attributes","slug":"using-attributes"},{"level":2,"title":"Optional nesting","slug":"optional-nesting"},{"level":2,"title":"Annotations must be associated with a structural element","slug":"annotations-must-be-associated-with-a-structural-element"},{"level":2,"title":"The PathParameter annotation","slug":"the-pathparameter-annotation"},{"level":2,"title":"The Attachable annotation","slug":"the-attachable-annotation"},{"level":2,"title":"Removed deprecated elements","slug":"removed-deprecated-elements"},{"level":3,"title":"\\\\Openapi\\\\Analysis::processors()","slug":"openapi-analysis-processors"},{"level":3,"title":"\\\\Openapi\\\\Analyser::$whitelist","slug":"openapi-analyser-whitelist"},{"level":3,"title":"\\\\Openapi\\\\Analyser::$defaultImports","slug":"openapi-analyser-defaultimports"},{"level":3,"title":"\\\\Openapi\\\\Logger","slug":"openapi-logger"},{"level":2,"title":"Improvements to the Generator class","slug":"improvements-to-the-generator-class"}],"relativePath":"guide/migrating-to-v4.md"}',t={},o=e("",41),p=[o];function i(c,l,r,u,d,h){return s(),n("div",null,p)}var g=a(t,[["render",i]]);export{m as __pageData,g as default}; diff --git a/assets/guide_required-elements.md.13284533.js b/assets/guide_required-elements.md.13284533.js new file mode 100644 index 000000000..cf1cad4bc --- /dev/null +++ b/assets/guide_required-elements.md.13284533.js @@ -0,0 +1,66 @@ +import{_ as o,c,b as p,w as a,a as t,r as i,o as l,d as n,e as s}from"./app.d3800f98.js";const O='{"title":"Required elements","description":"","frontmatter":{},"headers":[{"level":2,"title":"Minimum required annotations","slug":"minimum-required-annotations"},{"level":2,"title":"Optional elements","slug":"optional-elements"}],"relativePath":"guide/required-elements.md"}',u={},r=t('

Required elements

The OpenAPI specification defines a minimum set of information for a valid document.

For the most part that consists of some general information about the API like name, version and at least one endpoint.

The endpoint, in turn, needs to have a path and at least one response.

Minimum required annotations

With the above in mind a minimal API with a single endpoint could look like this

',6),k=n("div",{class:"language-php"},[n("pre",null,[n("code",null,[n("span",{class:"token php language-php"},[n("span",{class:"token delimiter important"},"with the resulting OpenAPI document like this

openapi: 3.0.0
+info:
+  title: 'My First API'
+  version: '0.1'
+paths:
+  /api/data.json:
+    get:
+      operationId: 236f26ae21b015a60adbce41f8f316e3
+      responses:
+        '200':
+          description: 'The data'
+

Code locations

Attributes and annotations can be added anywhere on declarations in code as defined by the PHP docs. These are limited to the extent of what the PHP Reflection APIs supports.

Optional elements

Looking at the generated document you will notice that there are some elements that swagger-php adds automatically when they are missing.

For the most part those are @OA\\OpenApi, @OA\\Components and @OA\\PathItem.

`,6);function h(_,f,g,y,b,A){const e=i("codeblock");return l(),c("div",null,[r,p(e,{id:"minimal"},{an:a(()=>[k]),at:a(()=>[d]),_:1}),m])}var q=o(u,[["render",h]]);export{O as __pageData,q as default}; diff --git a/assets/guide_required-elements.md.13284533.lean.js b/assets/guide_required-elements.md.13284533.lean.js new file mode 100644 index 000000000..5301fcd25 --- /dev/null +++ b/assets/guide_required-elements.md.13284533.lean.js @@ -0,0 +1,55 @@ +import{_ as o,c,b as p,w as a,a as t,r as i,o as l,d as n,e as s}from"./app.d3800f98.js";const O='{"title":"Required elements","description":"","frontmatter":{},"headers":[{"level":2,"title":"Minimum required annotations","slug":"minimum-required-annotations"},{"level":2,"title":"Optional elements","slug":"optional-elements"}],"relativePath":"guide/required-elements.md"}',u={},r=t("",6),k=n("div",{class:"language-php"},[n("pre",null,[n("code",null,[n("span",{class:"token php language-php"},[n("span",{class:"token delimiter important"},"[k]),at:a(()=>[d]),_:1}),m])}var q=o(u,[["render",h]]);export{O as __pageData,q as default}; diff --git a/assets/guide_under-the-hood.md.19c62cc3.js b/assets/guide_under-the-hood.md.19c62cc3.js new file mode 100644 index 000000000..dd9143a91 --- /dev/null +++ b/assets/guide_under-the-hood.md.19c62cc3.js @@ -0,0 +1,3 @@ +import{_ as e,c as t,o as a,a as o}from"./app.d3800f98.js";const g='{"title":"Under the hood","description":"","frontmatter":{},"headers":[{"level":2,"title":"Processing flow","slug":"processing-flow"},{"level":2,"title":"Context","slug":"context"},{"level":2,"title":"Analysis","slug":"analysis"},{"level":2,"title":"Documentation","slug":"documentation"},{"level":3,"title":"Installation","slug":"installation"},{"level":3,"title":"Workflow","slug":"workflow"}],"relativePath":"guide/under-the-hood.md"}',n={},i=o(`

Under the hood

Processing flow

  • The Generator iterates over the given sources (Symfony Finder, file/directory list, etc)
  • The configured analyser (AnalyserInterface) reads the files and builds an Analysis object. Default (as of v4) is the ReflectionAnalyser. Alternatively, there is the TokenAnalyser which was the default in v3.
  • The Analysis object and its annotations are then processed by the configured processors.
  • If enabled, the analysis/annotations are validated.
  • The root OpenApi annotation then contains all annotations and is serialized into YAML/JSON.

Context

Each annotation is associated with a unique Context instance. This contains details, collected by the parser/analyser, about the PHP context where the annotation was found.

Typically, there will be a processor that uses the data to augment/enrich the annotation.

Examples of the data collected:

  • class/interface/trait/enum names
  • property names
  • doctype or native type hints
  • file name and line number

Analysis

Contains all detected annotations and other relevant meta-data.

It uses a SplObjectStorage instance to store the parsed annotations.

Documentation

This documentation is generated with VitePress

Installation 

cd docs
+npm install vitepress 
+

Workflow

  • Edit .md files in the docs folder
  • Update annotation / attribute PHP docblocks.
    These will be extracted during publishing into the reference section.
  • Run 'composer docs:build' to check for any errors
  • Run 'composer docs:dev' to test the generated documentation locally (localhost:3000)
  • Create PR and update master
  • Manually trigger the gh-pages workflow to update the online docs.

The last step requires commit rights on zircote/swagger-php.

`,18),s=[i];function l(r,d,c,h,u,p){return a(),t("div",null,s)}var m=e(n,[["render",l]]);export{g as __pageData,m as default}; diff --git a/assets/guide_under-the-hood.md.19c62cc3.lean.js b/assets/guide_under-the-hood.md.19c62cc3.lean.js new file mode 100644 index 000000000..1c7680b14 --- /dev/null +++ b/assets/guide_under-the-hood.md.19c62cc3.lean.js @@ -0,0 +1 @@ +import{_ as e,c as t,o as a,a as o}from"./app.d3800f98.js";const g='{"title":"Under the hood","description":"","frontmatter":{},"headers":[{"level":2,"title":"Processing flow","slug":"processing-flow"},{"level":2,"title":"Context","slug":"context"},{"level":2,"title":"Analysis","slug":"analysis"},{"level":2,"title":"Documentation","slug":"documentation"},{"level":3,"title":"Installation","slug":"installation"},{"level":3,"title":"Workflow","slug":"workflow"}],"relativePath":"guide/under-the-hood.md"}',n={},i=o("",18),s=[i];function l(r,d,c,h,u,p){return a(),t("div",null,s)}var m=e(n,[["render",l]]);export{g as __pageData,m as default}; diff --git a/assets/index.md.59a0a95e.js b/assets/index.md.59a0a95e.js new file mode 100644 index 000000000..c324b0351 --- /dev/null +++ b/assets/index.md.59a0a95e.js @@ -0,0 +1,57 @@ +import{_ as o,c,b as i,w as a,a as s,r as p,o as l,d as n,e}from"./app.d3800f98.js";const x='{"title":"Home","description":"","frontmatter":{"home":true,"actionText":"User Guide \u2192","actionLink":"/guide/","features":[{"title":"OpenAPI conformant","details":"Generate OpenAPI documents in version 3.0 or 3.1."},{"title":"Document your API inside PHP source code","details":"Using swagger-php lets you write the API documentation inside the PHP source files which helps keeping the documentation up-to-date."},{"title":"Annotation and Attribute support","details":"Annotations can be either docblocks or PHP 8.1 attributes."}]},"headers":[{"level":3,"title":"1. Install with composer:","slug":"_1-install-with-composer"},{"level":3,"title":"2. Update your code","slug":"_2-update-your-code"},{"level":3,"title":"3. Generate OpenAPI documentation","slug":"_3-generate-openapi-documentation"},{"level":3,"title":"4. Explore and interact with your API","slug":"_4-explore-and-interact-with-your-api"},{"level":2,"title":"Links","slug":"links"}],"relativePath":"index.md"}',r={},u=s(`

1. Install with composer: 

> composer require zircote/swagger-php
+

2. Update your code

Add swagger-php annotations or attributes to your source code.

`,4),d=n("div",{class:"language-php"},[n("pre",null,[n("code",null,[n("span",{class:"token php language-php"},[n("span",{class:"token delimiter important"},"3. Generate OpenAPI documentation 
> ./bin/openapi src -o openapi.yaml
+

4. Explore and interact with your API

Use an OpenAPI tool like Swagger UI to explore and interact with your API.

`,6);function m(g,_,f,b,A,w){const t=p("codeblock");return l(),c("div",null,[u,i(t,{id:"minimal"},{an:a(()=>[d]),at:a(()=>[k]),_:1}),h])}var P=o(r,[["render",m]]);export{x as __pageData,P as default}; diff --git a/assets/index.md.59a0a95e.lean.js b/assets/index.md.59a0a95e.lean.js new file mode 100644 index 000000000..4c89bc94d --- /dev/null +++ b/assets/index.md.59a0a95e.lean.js @@ -0,0 +1,55 @@ +import{_ as o,c,b as i,w as a,a as s,r as p,o as l,d as n,e}from"./app.d3800f98.js";const x='{"title":"Home","description":"","frontmatter":{"home":true,"actionText":"User Guide \u2192","actionLink":"/guide/","features":[{"title":"OpenAPI conformant","details":"Generate OpenAPI documents in version 3.0 or 3.1."},{"title":"Document your API inside PHP source code","details":"Using swagger-php lets you write the API documentation inside the PHP source files which helps keeping the documentation up-to-date."},{"title":"Annotation and Attribute support","details":"Annotations can be either docblocks or PHP 8.1 attributes."}]},"headers":[{"level":3,"title":"1. Install with composer:","slug":"_1-install-with-composer"},{"level":3,"title":"2. Update your code","slug":"_2-update-your-code"},{"level":3,"title":"3. Generate OpenAPI documentation","slug":"_3-generate-openapi-documentation"},{"level":3,"title":"4. Explore and interact with your API","slug":"_4-explore-and-interact-with-your-api"},{"level":2,"title":"Links","slug":"links"}],"relativePath":"index.md"}',r={},u=s("",4),d=n("div",{class:"language-php"},[n("pre",null,[n("code",null,[n("span",{class:"token php language-php"},[n("span",{class:"token delimiter important"},"[d]),at:a(()=>[k]),_:1}),h])}var P=o(r,[["render",m]]);export{x as __pageData,P as default}; diff --git a/assets/reference_annotations.md.cdba131a.js b/assets/reference_annotations.md.cdba131a.js new file mode 100644 index 000000000..1cf754582 --- /dev/null +++ b/assets/reference_annotations.md.cdba131a.js @@ -0,0 +1 @@ +import{_ as e,c as a,o as t,a as r}from"./app.d3800f98.js";const b='{"title":"Annotations","description":"","frontmatter":{},"headers":[{"level":2,"title":"AdditionalProperties","slug":"additionalproperties"},{"level":2,"title":"Attachable","slug":"attachable"},{"level":2,"title":"Components","slug":"components"},{"level":2,"title":"Contact","slug":"contact"},{"level":2,"title":"CookieParameter","slug":"cookieparameter"},{"level":2,"title":"Delete","slug":"delete"},{"level":2,"title":"Discriminator","slug":"discriminator"},{"level":2,"title":"Examples","slug":"examples"},{"level":2,"title":"ExternalDocumentation","slug":"externaldocumentation"},{"level":2,"title":"Flow","slug":"flow"},{"level":2,"title":"Get","slug":"get"},{"level":2,"title":"Head","slug":"head"},{"level":2,"title":"Header","slug":"header"},{"level":2,"title":"HeaderParameter","slug":"headerparameter"},{"level":2,"title":"Info","slug":"info"},{"level":2,"title":"Items","slug":"items"},{"level":2,"title":"JsonContent","slug":"jsoncontent"},{"level":2,"title":"License","slug":"license"},{"level":2,"title":"Link","slug":"link"},{"level":2,"title":"MediaType","slug":"mediatype"},{"level":2,"title":"OpenApi","slug":"openapi"},{"level":2,"title":"Options","slug":"options"},{"level":2,"title":"Parameter","slug":"parameter"},{"level":2,"title":"Patch","slug":"patch"},{"level":2,"title":"PathItem","slug":"pathitem"},{"level":2,"title":"PathParameter","slug":"pathparameter"},{"level":2,"title":"Post","slug":"post"},{"level":2,"title":"Property","slug":"property"},{"level":2,"title":"Put","slug":"put"},{"level":2,"title":"QueryParameter","slug":"queryparameter"},{"level":2,"title":"RequestBody","slug":"requestbody"},{"level":2,"title":"Response","slug":"response"},{"level":2,"title":"Schema","slug":"schema"},{"level":2,"title":"SecurityScheme","slug":"securityscheme"},{"level":2,"title":"Server","slug":"server"},{"level":2,"title":"ServerVariable","slug":"servervariable"},{"level":2,"title":"Tag","slug":"tag"},{"level":2,"title":"Trace","slug":"trace"},{"level":2,"title":"Webhook","slug":"webhook"},{"level":2,"title":"Xml","slug":"xml"},{"level":2,"title":"XmlContent","slug":"xmlcontent"}],"relativePath":"reference/annotations.md"}',n={},s=r('

Annotations

This page is generated automatically from the swagger-php sources.

For improvements head over to GitHub and create a PR \u{1F609}

In addition to this page, there are also a number of examples which might help you out.

AdditionalProperties

Allowed in

Schema, Property, Items, JsonContent, XmlContent, AdditionalProperties

Nested elements

Discriminator, Items, Property, ExternalDocumentation, Xml, AdditionalProperties, Attachable

Attachable

A container for custom data to be attached to an annotation.

These will be ignored by swagger-php but can be used for custom processing.

Allowed in

AdditionalProperties, Components, Contact, Delete, Discriminator, Examples, ExternalDocumentation, Flow, Get, Head, Header, Info, Items, JsonContent, License, Link, MediaType, OpenApi, Operation, Options, Parameter, Patch, PathItem, PathParameter, Post, Property, Put, RequestBody, Response, Schema, SecurityScheme, Server, ServerVariable, Tag, Trace, Webhook, Xml, XmlContent

Components

Holds a set of reusable objects for different aspects of the OA.

All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.

Allowed in

OpenApi

Nested elements

Response, Parameter, PathParameter, RequestBody, Examples, Header, SecurityScheme, Link, Schema, Attachable

Properties

callbacks : array

Reusable Callbacks.

Reference

Contact

Contact information for the exposed API.

Allowed in

Info

Nested elements

Attachable

Properties

name : string

The identifying name of the contact person/organization.

url : string

The URL pointing to the contact information.

email : string

The email address of the contact person/organization.

Reference

CookieParameter

A @OA\\Request cookie parameter.

Allowed in

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements

Schema, Examples, Attachable

Properties

in

This takes 'cookie' as the default location.

Delete

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Properties

method

No details available.

Discriminator

The discriminator is a specific object in a schema which is used to inform the consumer of the specification of an alternative schema based on the value associated with it.

This object is based on the JSON Schema Specification and uses a predefined subset of it. On top of this subset, there are extensions provided by this specification to allow for more complete documentation.

Allowed in

Schema, Property, AdditionalProperties, Items, JsonContent, XmlContent

Nested elements

Attachable

Properties

propertyName : string

The name of the property in the payload that will hold the discriminator value.

mapping : string[]

An object to hold mappings between payload values and schema names or references.

Reference

Examples

Allowed in

Components, Schema, Parameter, PathParameter, MediaType, JsonContent, XmlContent

Nested elements

Attachable

Properties

ref : string|class-string|object

The relative or absolute path to an example.

See: Using refs

example : string

The key into `#/components/examples`.

summary : string

Short description for the example.

description : string

Embedded literal example.

The value field and externalValue field are mutually exclusive.

To represent examples of media types that cannot naturally be represented
in JSON or YAML, use a string value to contain the example, escaping where necessary.

value : int|string|array

Embedded literal example.

The value field and externalValue field are mutually exclusive.

To represent examples of media types that cannot naturally be represented
in JSON or YAML, use a string value to contain the example, escaping where necessary.

externalValue : string

An URL that points to the literal example.

This provides the capability to reference examples that cannot easily be included
in JSON or YAML documents.

The value field and externalValue field are mutually exclusive.

ExternalDocumentation

Allows referencing an external resource for extended documentation.

Allowed in

OpenApi, Tag, Schema, AdditionalProperties, Property, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace, Items, JsonContent, XmlContent

Nested elements

Attachable

Properties

description : string

A short description of the target documentation. GFM syntax can be used for rich text representation.

url : string

The URL for the target documentation.

Reference

Flow

Configuration details for a supported OAuth Flow.

Allowed in

SecurityScheme

Nested elements

Attachable

Properties

authorizationUrl : string

The authorization url to be used for this flow.

This must be in the form of an url.

tokenUrl : string

The token URL to be used for this flow.

This must be in the form of an url.

refreshUrl : string

The URL to be used for obtaining refresh tokens.

This must be in the form of an url.

flow : string

Flow name.

One of ['implicit', 'password', 'authorizationCode', 'clientCredentials'].

scopes : array

The available scopes for the OAuth2 security scheme.

A map between the scope name and a short description for it.

Reference

Get

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Properties

method

No details available.

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Properties

method

No details available.

Allowed in

Components, Response

Nested elements

Schema, Attachable

Properties

ref : string|class-string|object

The relative or absolute path to the endpoint.

See: Using refs

header : string

No details available.

description : string

A brief description of the parameter.

This could contain examples of use.
CommonMark syntax MAY be used for rich text representation.

required : bool

No details available.

deprecated : bool

Specifies that a parameter is deprecated and SHOULD be transitioned out of usage.

allowEmptyValue : bool

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored.

Reference

HeaderParameter

A @OA\\Request header parameter.

Allowed in

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements

Schema, Examples, Attachable

Properties

in

This takes 'header' as the default location.

Info

The object provides metadata about the API.

The metadata may be used by the clients if needed and may be presented in editing or documentation generation tools for convenience.

Allowed in

OpenApi

Nested elements

Contact, License, Attachable

Properties

title : string

The title of the application.

description : string

A short description of the application.

CommonMark syntax may be used for rich text representation.

termsOfService : string

An URL to the Terms of Service for the API.

Must be in the format of an url.

version : string

The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).

Reference

Items

The description of an item in a Schema with type array.

Allowed in

Property, AdditionalProperties, Schema, JsonContent, XmlContent, Items

Nested elements

Discriminator, Items, Property, ExternalDocumentation, Xml, AdditionalProperties, Attachable

JsonContent

Shorthand for a json response.

Use as @OA\\Schema inside a Response and MediaType->'application/json' will be generated.

Nested elements

Discriminator, Items, Property, ExternalDocumentation, AdditionalProperties, Examples, Attachable

License

License information for the exposed API.

Allowed in

Info

Nested elements

Attachable

Properties

name : string

The license name used for the API.

identifier : string

An SPDX license expression for the API. The `identifier` field is mutually exclusive of the `url` field.

url : string

An URL to the license used for the API. This MUST be in the form of a URL.

The `url` field is mutually exclusive of the `identifier` field.

Reference

The Link object represents a possible design-time link for a response.

The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations.

Unlike dynamic links (i.e. links provided in the response payload), the OA linking mechanism does not require link information in the runtime response.

For computing links, and providing instructions to execute them, a runtime expression is used for accessing values in an operation and using them as parameters while invoking the linked operation.

Allowed in

Components, Response

Nested elements

Server, Attachable

Properties

ref : string|class-string|object

No details available.

See: Using refs

link : string

The key into MediaType->links array.

operationRef : string

A relative or absolute reference to an OA operation.

This field is mutually exclusive of the operationId field, and must point to an Operation object.

Relative values may be used to locate an existing Operation object in the OpenAPI definition.

operationId : string

The name of an existing, resolvable OA operation, as defined with a unique operationId.

This field is mutually exclusive of the operationRef field.

parameters : array<string,mixed>

A map representing parameters to pass to an operation as specified with operationId or identified via
operationRef.

The key is the parameter name to be used, whereas the value can be a constant or an expression to
be evaluated and passed to the linked operation.
The parameter name can be qualified using the parameter location [{in}.]{name} for operations
that use the same parameter name in different locations (e.g. path.id).

requestBody

A literal value or {expression} to use as a request body when calling the target operation.

description : string

A description of the link.

CommonMark syntax may be used for rich text representation.

Reference

MediaType

Each Media Type object provides schema and examples for the media type identified by its key.

Allowed in

Response, RequestBody

Nested elements

Schema, Examples, Attachable

Properties

mediaType : string

The key into Operation->content array.

example

Example of the media type.

The example object should be in the correct format as specified by the media type.
The example object is mutually exclusive of the examples object.

Furthermore, if referencing a schema which contains an example,
the example value shall override the example provided by the schema.

encoding : array<string,mixed>

A map between a property name and its encoding information.

The key, being the property name, must exist in the schema as a property.

The encoding object shall only apply to requestBody objects when the media type is multipart or
application/x-www-form-urlencoded.

Reference

OpenApi

This is the root document object for the API specification.

Nested elements

Info, Server, PathItem, Components, Tag, ExternalDocumentation, Webhook, Attachable

Properties

openapi : string

The semantic version number of the OpenAPI Specification version that the OpenAPI document uses.

The openapi field should be used by tooling specifications and clients to interpret the OpenAPI document.

A version specified via `Generator::setVersion()` will overwrite this value.

This is not related to the API info::version string.

security : array

A declaration of which security mechanisms can be used across the API.

The list of values includes alternative security requirement objects that can be used.
Only one of the security requirement objects need to be satisfied to authorize a request.
Individual operations can override this definition.
To make security optional, an empty security requirement `({})` can be included in the array.

Reference

Options

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Properties

method

No details available.

Parameter

Describes a single operation parameter.

A unique parameter is defined by a combination of a name and location.

Allowed in

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements

Schema, Examples, Attachable

Properties

ref : string|class-string|object

The relative or absolute path to the endpoint.

See: Using refs

parameter : string

The key into Components::parameters or PathItem::parameters array.

name : string

The (case-sensitive) name of the parameter.

If in is "path", the name field must correspond to the associated path segment from the path field in the Paths Object.

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition shall be ignored.
For all other cases, the name corresponds to the parameter name used by the in property.

in : string

The location of the parameter.

Possible values are "query", "header", "path" or "cookie".

description : string

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

required : bool

Determines whether this parameter is mandatory.

If the parameter location is "path", this property is required and its value must be true.
Otherwise, the property may be included and its default value is false.

deprecated : bool

Specifies that a parameter is deprecated and should be transitioned out of usage.

allowEmptyValue : bool

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue shall be ignored.

style : string

Describes how the parameter value will be serialized depending on the type of the parameter value.

Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

explode : bool

When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.

For other types of parameters this property has no effect.

When style is form, the default value is true.
For all other styles, the default value is false.

allowReserved : bool

Determines whether the parameter value should allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.

This property only applies to parameters with an in value of query.

The default value is false.

example

Example of the media type.

The example should match the specified schema and encoding properties if present.
The example object is mutually exclusive of the examples object.
Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema.
To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

content : array<MediaType>|JsonContent|XmlContent|Attachable

A map containing the representations for the parameter.

The key is the media type and the value describes it.
The map must only contain one entry.

matrix

Path-style parameters defined by RFC6570.

See: RFC6570

label

Label style parameters defined by RFC6570.

See: RFC6570

form

Form style parameters defined by RFC6570.

This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.

See: RFC6570

simple : array

Simple style parameters defined by RFC6570.

This option replaces collectionFormat with a csv value from OpenAPI 2.0.

See: RFC6570

spaceDelimited : array

Space separated array values.

This option replaces collectionFormat equal to ssv from OpenAPI 2.0.

pipeDelimited : array

Pipe separated array values.

This option replaces collectionFormat equal to pipes from OpenAPI 2.0.

deepObject

Provides a simple way of rendering nested objects using form parameters.

Reference

Patch

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Properties

method

No details available.

PathItem

Describes the operations available on a single path.

A Path Item may be empty, due to ACL constraints. The path itself is still exposed to the documentation viewer, but they will not know which operations and parameters are available.

Allowed in

OpenApi

Nested elements

Get, Post, Put, Delete, Patch, Trace, Head, Options, Parameter, PathParameter, Server, Attachable

Properties

ref : string|class-string|object

No details available.

See: Using refs

summary : string

An optional, string summary, intended to apply to all operations in this path.

description : string

An optional, string description, intended to apply to all operations in this path.

path : string

Key for the Path Object (OpenApi->paths array).

Reference

PathParameter

A @OA\\Request path parameter.

Allowed in

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements

Schema, Examples, Attachable

Properties

in

This takes 'path' as the default location.

required

No details available.

Post

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Properties

method

No details available.

Property

Allowed in

AdditionalProperties, Schema, JsonContent, XmlContent, Property, Items

Nested elements

Discriminator, Items, Property, ExternalDocumentation, Xml, AdditionalProperties, Attachable

Properties

property : string

The key into Schema->properties array.

Put

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Properties

method

No details available.

QueryParameter

A @OA\\Request query parameter.

Allowed in

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements

Schema, Examples, Attachable

Properties

in

This takes 'query' as the default location.

RequestBody

Describes a single request body.

Allowed in

Components, Delete, Get, Head, Operation, Options, Patch, Post, Trace, Put

Nested elements

MediaType, Attachable

Properties

ref : string|class-string|object

The relative or absolute path to a request body.

See: Using refs

request : string

The key into Components->requestBodies array.

description : string

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

required : bool

Determines whether this parameter is mandatory.

If the parameter location is "path", this property is required and its value must be true.
Otherwise, the property may be included and its default value is false.

Reference

Response

Describes a single response from an API Operation, including design-time, static links to operations based on the response.

Allowed in

Components, Operation, Get, Post, Put, Patch, Delete, Head, Options, Trace

Nested elements

MediaType, Header, Link, Attachable

Properties

ref : string|class-string|object

The relative or absolute path to a response.

See: Using refs

response : string|int

The key into Operations->responses array.

A HTTP status code or default.

description : string

A short description of the response.

CommonMark syntax may be used for rich text representation.

Reference

Schema

The definition of input and output data types.

These types can be objects, but also primitives and arrays.

This object is based on the JSON Schema Specification and uses a predefined subset of it. On top of this subset, there are extensions provided by this specification to allow for more complete documentation.

Allowed in

Components, Parameter, PathParameter, MediaType, Header

Nested elements

Discriminator, Items, Property, ExternalDocumentation, Examples, Xml, AdditionalProperties, Attachable

Properties

ref : string|class-string|object

The relative or absolute path to the endpoint.

See: Using refs

schema : string

The key into Components->schemas array.

title : string

Can be used to decorate a user interface with information about the data produced by this user interface.

Preferably short; use description for more details.

description : string

A description will provide explanation about the purpose of the instance described by this schema.

maxProperties : int

The maximum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is less than, or equal to, the
value of this attribute.

minProperties : int

The minimum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is greater than, or equal to, the
value of this attribute.

required : string[]

An object instance is valid against this property if its property set contains all elements in this property's
array value.

type : string|non-empty-array<string>

The type of the schema/property.

OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".

Since OpenApi v3.1 an array of types may be used.

format : string

The extending format for the previously mentioned type. See Data Type Formats for further details.

collectionFormat : string

Determines the format of the array if type array is used.

Possible values are:
- csv: comma separated values foo,bar.
- ssv: space separated values foo bar.
- tsv: tab separated values foo\\tbar.
- pipes: pipe separated values foo|bar.
- multi: corresponds to multiple parameter instances instead of multiple values for a single instance
foo=bar&foo=baz. This is valid only for parameters of type query or formData. Default
value is csv.

default

Sets a default value to the parameter. The type of the value depends on the defined type.

See: JSON schema validation

maximum : int|float

The maximum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMaximum : bool|int|float

A boolean indicating whether the maximum value is excluded from the set of valid values.

When set to true, the maximum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

minimum : int|float

The minimum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMinimum : bool|int|float

A boolean indicating whether the minimum value is excluded from the set of valid values.

When set to true, the minimum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

maxLength : int

The maximum length of a string property.

A string instance is valid against this property if its length is less than, or equal to, the value of this
attribute.

See: JSON schema validation

minLength : int

The minimum length of a string property.

A string instance is valid against this property if its length is greater than, or equal to, the value of this
attribute.

See: JSON schema validation

pattern : string

A string instance is considered valid if the regular expression matches the instance successfully.

maxItems : int

The maximum number of items allowed in an array property.

An array instance is valid against this property if its number of items is less than, or equal to, the value of
this attribute.

See: JSON schema validation

minItems : int

The minimum number of items allowed in an array property.

An array instance is valid against this property if its number of items is greater than, or equal to, the value
of this attribute.

See: JSON schema validation

uniqueItems : bool

A boolean value indicating whether all items in an array property must be unique.

If this attribute is set to true, then all items in the array must be unique.

See: JSON schema validation

enum : array<string|int|float|bool|\\UnitEnum>|class-string

A collection of allowable values for a property.

A property instance is valid against this attribute if its value is one of the values specified in this
collection.

See: JSON schema validation

multipleOf : int|float

A numeric instance is valid against "multipleOf" if the result of the division of the instance by this
property's value is an integer.

readOnly : bool

Declares the property as "read only".

Relevant only for Schema "properties" definitions.

This means that it may be sent as part of a response but should not be sent as part of the request.
If the property is marked as readOnly being true and is in the required list, the required will take effect on
the response only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

writeOnly : bool

Declares the property as "write only".

Relevant only for Schema "properties" definitions.
Therefore, it may be sent as part of a request but should not be sent as part of the response.
If the property is marked as writeOnly being true and is in the required list, the required will take effect on
the request only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

example

A free-form property to include an example of an instance for this schema.

To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
contain the example with escaping where necessary.

nullable : bool

Allows sending a null value for the defined schema.
Default value is false.

This must not be used when using OpenApi version 3.1,
instead make the "type" property an array and add "null" as a possible type.

deprecated : bool

Specifies that a schema is deprecated and should be transitioned out of usage.
Default value is false.

allOf : array<Schema|\\OpenApi\\Attributes\\Schema>

An instance validates successfully against this property if it validates successfully against all schemas
defined by this property's value.

anyOf : array<Schema|\\OpenApi\\Attributes\\Schema>

An instance validates successfully against this property if it validates successfully against at least one
schema defined by this property's value.

oneOf : array<Schema|\\OpenApi\\Attributes\\Schema>

An instance validates successfully against this property if it validates successfully against exactly one schema
defined by this property's value.

not

http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.29.

additionalItems

http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.10.

contains

http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.14.

patternProperties

http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.19.

dependencies

http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.21.

propertyNames

http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.22.

const

http://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.1.3.

Reference

SecurityScheme

Allowed in

Components

Nested elements

Flow, Attachable

Properties

ref : string|class-string|object

The relative or absolute path to a security scheme.

See: Using refs

securityScheme : string

The key into OpenApi->security array.

type : string|non-empty-array<string>

The type of the security scheme.

description : string

A short description for security scheme.

name : string

The name of the header or query parameter to be used.

in : string

Required The location of the API key.

bearerFormat : string

A hint to the client to identify how the bearer token is formatted.

Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.

scheme : string

The name of the HTTP Authorization scheme.

See: RFC7235

openIdConnectUrl : string

OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL.

Reference

Server

An object representing a server.

Allowed in

OpenApi, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace, Link

Nested elements

ServerVariable, Attachable

Properties

url : string

An URL to the target host.

This URL supports Server Variables and may be relative,
to indicate that the host location is relative to the location where the OpenAPI document is being served.
Variable substitutions will be made when a variable is named in {brackets}.

description : string

An optional string describing the host designated by the URL.

CommonMark syntax may be used for rich text representation.

Reference

ServerVariable

An object representing a server variable for server URL template substitution.

Allowed in

Server

Nested elements

Attachable

Properties

serverVariable : string

The key into Server->variables array.

enum : array<string|int|float|bool|\\UnitEnum>|class-string

An enumeration of values to be used if the substitution options are from a limited set.

default : string

The default value to use for substitution, and to send, if an alternate value is not supplied.

Unlike the Schema Object's default, this value must be provided by the consumer.

variables : array

A map between a variable name and its value.

The value is used for substitution in the server's URL template.

description : string

An optional description for the server variable.

CommonMark syntax MAY be used for rich text representation.

Reference

Tag

Allowed in

OpenApi

Nested elements

ExternalDocumentation, Attachable

Properties

name : string

The name of the tag.

description : string

A short description for the tag. GFM syntax can be used for rich text representation.

Reference

Trace

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Properties

method

No details available.

Webhook

Acts like a PathItem with the main difference being that it requires webhook instead of path.

Allowed in

OpenApi

Nested elements

Get, Post, Put, Delete, Patch, Trace, Head, Options, Parameter, PathParameter, Server, Attachable

Properties

webhook : string

Key for the webhooks map.

Xml

Allowed in

AdditionalProperties, Schema, Property, Schema, Items, XmlContent

Nested elements

Attachable

Properties

name : string

Replaces the name of the element/attribute used for the described schema property.

When defined within the Items Object (items), it will affect the name of the individual XML elements within the list.
When defined alongside type being array (outside the items), it will affect the wrapping element
and only if wrapped is true.

If wrapped is false, it will be ignored.

namespace : string

The URL of the namespace definition. Value SHOULD be in the form of a URL.

prefix : string

The prefix to be used for the name.

attribute : bool

Declares whether the property definition translates to an attribute instead of an element.

Default value is false.

wrapped : bool

MAY be used only for an array definition.

Signifies whether the array is wrapped (for example <books><book/><book/></books>)
or unwrapped (<book/><book/>).

Default value is false. The definition takes effect only when defined alongside type being array (outside the items).

Reference

XmlContent

Shorthand for a xml response.

Use as @OA\\Schema inside a Response and MediaType->'application/xml' will be generated.

Nested elements

Discriminator, Items, Property, ExternalDocumentation, Xml, AdditionalProperties, Examples, Attachable

',489),o=[s];function i(d,h,p,l,c,f){return t(),a("div",null,o)}var u=e(n,[["render",i]]);export{b as __pageData,u as default}; diff --git a/assets/reference_annotations.md.cdba131a.lean.js b/assets/reference_annotations.md.cdba131a.lean.js new file mode 100644 index 000000000..d371fdeb4 --- /dev/null +++ b/assets/reference_annotations.md.cdba131a.lean.js @@ -0,0 +1 @@ +import{_ as e,c as a,o as t,a as r}from"./app.d3800f98.js";const b='{"title":"Annotations","description":"","frontmatter":{},"headers":[{"level":2,"title":"AdditionalProperties","slug":"additionalproperties"},{"level":2,"title":"Attachable","slug":"attachable"},{"level":2,"title":"Components","slug":"components"},{"level":2,"title":"Contact","slug":"contact"},{"level":2,"title":"CookieParameter","slug":"cookieparameter"},{"level":2,"title":"Delete","slug":"delete"},{"level":2,"title":"Discriminator","slug":"discriminator"},{"level":2,"title":"Examples","slug":"examples"},{"level":2,"title":"ExternalDocumentation","slug":"externaldocumentation"},{"level":2,"title":"Flow","slug":"flow"},{"level":2,"title":"Get","slug":"get"},{"level":2,"title":"Head","slug":"head"},{"level":2,"title":"Header","slug":"header"},{"level":2,"title":"HeaderParameter","slug":"headerparameter"},{"level":2,"title":"Info","slug":"info"},{"level":2,"title":"Items","slug":"items"},{"level":2,"title":"JsonContent","slug":"jsoncontent"},{"level":2,"title":"License","slug":"license"},{"level":2,"title":"Link","slug":"link"},{"level":2,"title":"MediaType","slug":"mediatype"},{"level":2,"title":"OpenApi","slug":"openapi"},{"level":2,"title":"Options","slug":"options"},{"level":2,"title":"Parameter","slug":"parameter"},{"level":2,"title":"Patch","slug":"patch"},{"level":2,"title":"PathItem","slug":"pathitem"},{"level":2,"title":"PathParameter","slug":"pathparameter"},{"level":2,"title":"Post","slug":"post"},{"level":2,"title":"Property","slug":"property"},{"level":2,"title":"Put","slug":"put"},{"level":2,"title":"QueryParameter","slug":"queryparameter"},{"level":2,"title":"RequestBody","slug":"requestbody"},{"level":2,"title":"Response","slug":"response"},{"level":2,"title":"Schema","slug":"schema"},{"level":2,"title":"SecurityScheme","slug":"securityscheme"},{"level":2,"title":"Server","slug":"server"},{"level":2,"title":"ServerVariable","slug":"servervariable"},{"level":2,"title":"Tag","slug":"tag"},{"level":2,"title":"Trace","slug":"trace"},{"level":2,"title":"Webhook","slug":"webhook"},{"level":2,"title":"Xml","slug":"xml"},{"level":2,"title":"XmlContent","slug":"xmlcontent"}],"relativePath":"reference/annotations.md"}',n={},s=r("",489),o=[s];function i(d,h,p,l,c,f){return t(),a("div",null,o)}var u=e(n,[["render",i]]);export{b as __pageData,u as default}; diff --git a/assets/reference_attributes.md.e96acd84.js b/assets/reference_attributes.md.e96acd84.js new file mode 100644 index 000000000..a6313b74f --- /dev/null +++ b/assets/reference_attributes.md.e96acd84.js @@ -0,0 +1 @@ +import{_ as e,c as t,o as a,a as n}from"./app.d3800f98.js";const u='{"title":"Attributes","description":"","frontmatter":{},"headers":[{"level":2,"title":"AdditionalProperties","slug":"additionalproperties"},{"level":2,"title":"Attachable","slug":"attachable"},{"level":2,"title":"Components","slug":"components"},{"level":2,"title":"Contact","slug":"contact"},{"level":2,"title":"CookieParameter","slug":"cookieparameter"},{"level":2,"title":"Delete","slug":"delete"},{"level":2,"title":"Discriminator","slug":"discriminator"},{"level":2,"title":"Examples","slug":"examples"},{"level":2,"title":"ExternalDocumentation","slug":"externaldocumentation"},{"level":2,"title":"Flow","slug":"flow"},{"level":2,"title":"Get","slug":"get"},{"level":2,"title":"Head","slug":"head"},{"level":2,"title":"Header","slug":"header"},{"level":2,"title":"HeaderParameter","slug":"headerparameter"},{"level":2,"title":"Info","slug":"info"},{"level":2,"title":"Items","slug":"items"},{"level":2,"title":"JsonContent","slug":"jsoncontent"},{"level":2,"title":"License","slug":"license"},{"level":2,"title":"Link","slug":"link"},{"level":2,"title":"MediaType","slug":"mediatype"},{"level":2,"title":"OpenApi","slug":"openapi"},{"level":2,"title":"Options","slug":"options"},{"level":2,"title":"Parameter","slug":"parameter"},{"level":2,"title":"Patch","slug":"patch"},{"level":2,"title":"PathItem","slug":"pathitem"},{"level":2,"title":"PathParameter","slug":"pathparameter"},{"level":2,"title":"Post","slug":"post"},{"level":2,"title":"Property","slug":"property"},{"level":2,"title":"Put","slug":"put"},{"level":2,"title":"QueryParameter","slug":"queryparameter"},{"level":2,"title":"RequestBody","slug":"requestbody"},{"level":2,"title":"Response","slug":"response"},{"level":2,"title":"Schema","slug":"schema"},{"level":2,"title":"SecurityScheme","slug":"securityscheme"},{"level":2,"title":"Server","slug":"server"},{"level":2,"title":"ServerVariable","slug":"servervariable"},{"level":2,"title":"Tag","slug":"tag"},{"level":2,"title":"Trace","slug":"trace"},{"level":2,"title":"Webhook","slug":"webhook"},{"level":2,"title":"Xml","slug":"xml"},{"level":2,"title":"XmlContent","slug":"xmlcontent"}],"relativePath":"reference/attributes.md"}',s={},r=n('

Attributes

This page is generated automatically from the swagger-php sources.

For improvements head over to GitHub and create a PR \u{1F609}

In addition to this page, there are also a number of examples which might help you out.

AdditionalProperties

Allowed in

Schema, Property, Items, JsonContent, XmlContent, AdditionalProperties

Nested elements

Discriminator, Items, Property, ExternalDocumentation, Xml, AdditionalProperties, Attachable

Parameters

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : string|null

The key into Components->schemas array.

title : string|null

Can be used to decorate a user interface with information about the data produced by this user interface.

Preferably short; use description for more details.

description : string|null

A description will provide explanation about the purpose of the instance described by this schema.

maxProperties : int|null

The maximum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is less than, or equal to, the
value of this attribute.

minProperties : int|null

The minimum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is greater than, or equal to, the
value of this attribute.

required : string[]

An object instance is valid against this property if its property set contains all elements in this property's
array value.

properties : Property[]

A collection of properties to define for an object.

Each property is represented as an instance of the Property class.

type : string|non-empty-array<string>|null

The type of the schema/property.

OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".

Since OpenApi v3.1 an array of types may be used.

format : string|null

The extending format for the previously mentioned type. See Data Type Formats for further details.

items : OpenApi\\Attributes\\Items|null

Required if type is "array". Describes the type of items in the array.

collectionFormat : string|null

Determines the format of the array if type array is used.

Possible values are:
- csv: comma separated values foo,bar.
- ssv: space separated values foo bar.
- tsv: tab separated values foo\\tbar.
- pipes: pipe separated values foo|bar.
- multi: corresponds to multiple parameter instances instead of multiple values for a single instance
foo=bar&foo=baz. This is valid only for parameters of type query or formData. Default
value is csv.

default : mixed|null

Sets a default value to the parameter. The type of the value depends on the defined type.

See: JSON schema validation

maximum : int|float

The maximum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMaximum : int|float|bool|null

A boolean indicating whether the maximum value is excluded from the set of valid values.

When set to true, the maximum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

minimum : int|float

The minimum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMinimum : int|float|bool|null

A boolean indicating whether the minimum value is excluded from the set of valid values.

When set to true, the minimum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

maxLength : int|null

The maximum length of a string property.

A string instance is valid against this property if its length is less than, or equal to, the value of this
attribute.

See: JSON schema validation

minLength : int|null

The minimum length of a string property.

A string instance is valid against this property if its length is greater than, or equal to, the value of this
attribute.

See: JSON schema validation

maxItems : int|null

The maximum number of items allowed in an array property.

An array instance is valid against this property if its number of items is less than, or equal to, the value of
this attribute.

See: JSON schema validation

minItems : int|null

The minimum number of items allowed in an array property.

An array instance is valid against this property if its number of items is greater than, or equal to, the value
of this attribute.

See: JSON schema validation

uniqueItems : bool|null

A boolean value indicating whether all items in an array property must be unique.

If this attribute is set to true, then all items in the array must be unique.

See: JSON schema validation

pattern : string|null

A string instance is considered valid if the regular expression matches the instance successfully.

enum : array<string|int|float|bool|\\UnitEnum|null>|class-string|null

A collection of allowable values for a property.

A property instance is valid against this attribute if its value is one of the values specified in this
collection.

See: JSON schema validation

discriminator : OpenApi\\Attributes\\Discriminator|null

Adds support for polymorphism.

The discriminator is an object name that is used to differentiate between other schemas which may satisfy the
payload description. See Composition and Inheritance for more details.

readOnly : bool|null

Declares the property as "read only".

Relevant only for Schema "properties" definitions.

This means that it may be sent as part of a response but should not be sent as part of the request.
If the property is marked as readOnly being true and is in the required list, the required will take effect on
the response only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

writeOnly : bool|null

Declares the property as "write only".

Relevant only for Schema "properties" definitions.
Therefore, it may be sent as part of a request but should not be sent as part of the response.
If the property is marked as writeOnly being true and is in the required list, the required will take effect on
the request only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

xml : OpenApi\\Attributes\\Xml|null

This may be used only on properties schemas.

It has no effect on root schemas.
Adds additional metadata to describe the XML representation of this property.

externalDocs : OpenApi\\Attributes\\ExternalDocumentation|null

Additional external documentation for this schema.

example : mixed|null

A free-form property to include an example of an instance for this schema.

To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
contain the example with escaping where necessary.

nullable : bool|null

Allows sending a null value for the defined schema.
Default value is false.

This must not be used when using OpenApi version 3.1,
instead make the "type" property an array and add "null" as a possible type.

deprecated : bool|null

Specifies that a schema is deprecated and should be transitioned out of usage.
Default value is false.

allOf : array<Schema|\\OpenApi\\Annotations\\Schema>

An instance validates successfully against this property if it validates successfully against all schemas
defined by this property's value.

anyOf : array<Schema|\\OpenApi\\Annotations\\Schema>

An instance validates successfully against this property if it validates successfully against at least one
schema defined by this property's value.

oneOf : array<Schema|\\OpenApi\\Annotations\\Schema>

An instance validates successfully against this property if it validates successfully against exactly one schema
defined by this property's value.

additionalProperties : OpenApi\\Attributes\\AdditionalProperties|bool|null

http://json-schema.org/latest/json-schema-validation.html#anchor64.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Attachable

Allowed in

AdditionalProperties, Components, Contact, Delete, Discriminator, Examples, ExternalDocumentation, Flow, Get, Head, Header, Info, Items, JsonContent, License, Link, MediaType, OpenApi, Operation, Options, Parameter, Patch, PathItem, PathParameter, Post, Property, Put, RequestBody, Response, Schema, SecurityScheme, Server, ServerVariable, Tag, Trace, Webhook, Xml, XmlContent

Parameters

properties : array

No details available.

Components

Allowed in

OpenApi

Nested elements

Response, Parameter, PathParameter, RequestBody, Examples, Header, SecurityScheme, Link, Schema, Attachable

Parameters

schemas : array<Schema|\\OpenApi\\Annotations\\Schema>|null

Reusable Schemas.

responses : Response[]|null

Reusable Responses.

parameters : Parameter[]|null

Reusable Parameters.

requestBodies : RequestBody[]|null

Reusable Request Bodies.

examples : array<Examples>|null

Reusable Examples.

headers : Header[]|null

Reusable Headers.

securitySchemes : SecurityScheme[]|null

Reusable Security Schemes.

links : Link[]|null

Reusable Links.

callbacks : array|null

Reusable Callbacks.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Contact

Allowed in

Info

Nested elements

Attachable

Parameters

name : string|null

The identifying name of the contact person/organization.

url : string|null

The URL pointing to the contact information.

email : string|null

The email address of the contact person/organization.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

CookieParameter

Allowed in

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements

Schema, Examples, Attachable

Parameters

parameter : string|null

The key into Components::parameters or PathItem::parameters array.

name : string|null

The (case-sensitive) name of the parameter.

If in is "path", the name field must correspond to the associated path segment from the path field in the Paths Object.

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition shall be ignored.
For all other cases, the name corresponds to the parameter name used by the in property.

description : string|null

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

in : string|null

This takes 'cookie' as the default location.

required : bool|null

Determines whether this parameter is mandatory.

If the parameter location is "path", this property is required and its value must be true.
Otherwise, the property may be included and its default value is false.

deprecated : bool|null

Specifies that a parameter is deprecated and should be transitioned out of usage.

allowEmptyValue : bool|null

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue shall be ignored.

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : OpenApi\\Attributes\\Schema|null

The schema defining the type used for the parameter.

example : mixed|null

Example of the media type.

The example should match the specified schema and encoding properties if present.
The example object is mutually exclusive of the examples object.
Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema.
To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

examples : array<Examples>

Examples of the parameter.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

content : array<MediaType>|JsonContent|XmlContent|Attachable|null

A map containing the representations for the parameter.

The key is the media type and the value describes it.
The map must only contain one entry.

style : string|null

Describes how the parameter value will be serialized depending on the type of the parameter value.

Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

explode : bool|null

When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.

For other types of parameters this property has no effect.

When style is form, the default value is true.
For all other styles, the default value is false.

allowReserved : bool|null

Determines whether the parameter value should allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.

This property only applies to parameters with an in value of query.

The default value is false.

spaceDelimited : array|null

Space separated array values.

This option replaces collectionFormat equal to ssv from OpenAPI 2.0.

pipeDelimited : array|null

Pipe separated array values.

This option replaces collectionFormat equal to pipes from OpenAPI 2.0.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Delete

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters

path : string|null

Key in the OpenApi "Paths Object" for this operation.

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

summary : string|null

A short summary of what the operation does.

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

requestBody : OpenApi\\Attributes\\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

responses : Response[]

The list of possible responses as they are returned from executing this operation.

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

externalDocs : OpenApi\\Attributes\\ExternalDocumentation|null

Additional external documentation for this operation.

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Discriminator

Allowed in

Schema, Property, AdditionalProperties, Items, JsonContent, XmlContent

Nested elements

Attachable

Parameters

propertyName : string|null

The name of the property in the payload that will hold the discriminator value.

mapping : string[]|null

An object to hold mappings between payload values and schema names or references.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Examples

Allowed in

Components, Schema, Parameter, PathParameter, MediaType, JsonContent, XmlContent

Nested elements

Attachable

Parameters

example : string|null

The key into `#/components/examples`.

summary : string|null

Short description for the example.

description : string|null

Embedded literal example.

The value field and externalValue field are mutually exclusive.

To represent examples of media types that cannot naturally be represented
in JSON or YAML, use a string value to contain the example, escaping where necessary.

value : array|string|int|null

Embedded literal example.

The value field and externalValue field are mutually exclusive.

To represent examples of media types that cannot naturally be represented
in JSON or YAML, use a string value to contain the example, escaping where necessary.

externalValue : string|null

An URL that points to the literal example.

This provides the capability to reference examples that cannot easily be included
in JSON or YAML documents.

The value field and externalValue field are mutually exclusive.

ref : string|class-string|object|null

The relative or absolute path to an example.

See: Using refs

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

ExternalDocumentation

Allowed in

OpenApi, Tag, Schema, AdditionalProperties, Property, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace, Items, JsonContent, XmlContent

Nested elements

Attachable

Parameters

description : string|null

A short description of the target documentation. GFM syntax can be used for rich text representation.

url : string|null

The URL for the target documentation.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Flow

Allowed in

SecurityScheme

Nested elements

Attachable

Parameters

authorizationUrl : string|null

The authorization url to be used for this flow.

This must be in the form of an url.

tokenUrl : string|null

The token URL to be used for this flow.

This must be in the form of an url.

refreshUrl : string|null

The URL to be used for obtaining refresh tokens.

This must be in the form of an url.

flow : string|null

Flow name.

One of ['implicit', 'password', 'authorizationCode', 'clientCredentials'].

scopes : array|null

The available scopes for the OAuth2 security scheme.

A map between the scope name and a short description for it.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Get

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters

path : string|null

Key in the OpenApi "Paths Object" for this operation.

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

summary : string|null

A short summary of what the operation does.

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

requestBody : OpenApi\\Attributes\\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

responses : Response[]

The list of possible responses as they are returned from executing this operation.

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

externalDocs : OpenApi\\Attributes\\ExternalDocumentation|null

Additional external documentation for this operation.

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters

path : string|null

Key in the OpenApi "Paths Object" for this operation.

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

summary : string|null

A short summary of what the operation does.

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

requestBody : OpenApi\\Attributes\\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

responses : Response[]

The list of possible responses as they are returned from executing this operation.

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

externalDocs : OpenApi\\Attributes\\ExternalDocumentation|null

Additional external documentation for this operation.

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Allowed in

Components, Response

Nested elements

Schema, Attachable

Parameters

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

header : string|null

No details available.

description : string|null

A brief description of the parameter.

This could contain examples of use.
CommonMark syntax MAY be used for rich text representation.

required : bool|null

No details available.

schema : OpenApi\\Attributes\\Schema|null

Schema object.

deprecated : bool|null

Specifies that a parameter is deprecated and SHOULD be transitioned out of usage.

allowEmptyValue : bool|null

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

HeaderParameter

Allowed in

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements

Schema, Examples, Attachable

Parameters

parameter : string|null

The key into Components::parameters or PathItem::parameters array.

name : string|null

The (case-sensitive) name of the parameter.

If in is "path", the name field must correspond to the associated path segment from the path field in the Paths Object.

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition shall be ignored.
For all other cases, the name corresponds to the parameter name used by the in property.

description : string|null

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

in : string|null

This takes 'header' as the default location.

required : bool|null

Determines whether this parameter is mandatory.

If the parameter location is "path", this property is required and its value must be true.
Otherwise, the property may be included and its default value is false.

deprecated : bool|null

Specifies that a parameter is deprecated and should be transitioned out of usage.

allowEmptyValue : bool|null

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue shall be ignored.

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : OpenApi\\Attributes\\Schema|null

The schema defining the type used for the parameter.

example : mixed|null

Example of the media type.

The example should match the specified schema and encoding properties if present.
The example object is mutually exclusive of the examples object.
Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema.
To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

examples : array<Examples>

Examples of the parameter.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

content : array<MediaType>|JsonContent|XmlContent|Attachable|null

A map containing the representations for the parameter.

The key is the media type and the value describes it.
The map must only contain one entry.

style : string|null

Describes how the parameter value will be serialized depending on the type of the parameter value.

Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

explode : bool|null

When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.

For other types of parameters this property has no effect.

When style is form, the default value is true.
For all other styles, the default value is false.

allowReserved : bool|null

Determines whether the parameter value should allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.

This property only applies to parameters with an in value of query.

The default value is false.

spaceDelimited : array|null

Space separated array values.

This option replaces collectionFormat equal to ssv from OpenAPI 2.0.

pipeDelimited : array|null

Pipe separated array values.

This option replaces collectionFormat equal to pipes from OpenAPI 2.0.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Info

Allowed in

OpenApi

Nested elements

Contact, License, Attachable

Parameters

version : string|null

The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).

description : string|null

A short description of the application.

CommonMark syntax may be used for rich text representation.

title : string|null

The title of the application.

termsOfService : string|null

An URL to the Terms of Service for the API.

Must be in the format of an url.

contact : OpenApi\\Attributes\\Contact|null

The contact information for the exposed API.

license : OpenApi\\Attributes\\License|null

The license information for the exposed API.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Items

Allowed in

Property, AdditionalProperties, Schema, JsonContent, XmlContent, Items

Nested elements

Discriminator, Items, Property, ExternalDocumentation, Xml, AdditionalProperties, Attachable

Parameters

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : string|null

The key into Components->schemas array.

title : string|null

Can be used to decorate a user interface with information about the data produced by this user interface.

Preferably short; use description for more details.

description : string|null

A description will provide explanation about the purpose of the instance described by this schema.

maxProperties : int|null

The maximum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is less than, or equal to, the
value of this attribute.

minProperties : int|null

The minimum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is greater than, or equal to, the
value of this attribute.

required : string[]

An object instance is valid against this property if its property set contains all elements in this property's
array value.

properties : Property[]

A collection of properties to define for an object.

Each property is represented as an instance of the Property class.

type : string|non-empty-array<string>|null

The type of the schema/property.

OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".

Since OpenApi v3.1 an array of types may be used.

format : string|null

The extending format for the previously mentioned type. See Data Type Formats for further details.

items : OpenApi\\Attributes\\Items|null

Required if type is "array". Describes the type of items in the array.

collectionFormat : string|null

Determines the format of the array if type array is used.

Possible values are:
- csv: comma separated values foo,bar.
- ssv: space separated values foo bar.
- tsv: tab separated values foo\\tbar.
- pipes: pipe separated values foo|bar.
- multi: corresponds to multiple parameter instances instead of multiple values for a single instance
foo=bar&foo=baz. This is valid only for parameters of type query or formData. Default
value is csv.

default : mixed|null

Sets a default value to the parameter. The type of the value depends on the defined type.

See: JSON schema validation

maximum : int|float

The maximum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMaximum : int|float|bool|null

A boolean indicating whether the maximum value is excluded from the set of valid values.

When set to true, the maximum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

minimum : int|float

The minimum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMinimum : int|float|bool|null

A boolean indicating whether the minimum value is excluded from the set of valid values.

When set to true, the minimum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

maxLength : int|null

The maximum length of a string property.

A string instance is valid against this property if its length is less than, or equal to, the value of this
attribute.

See: JSON schema validation

minLength : int|null

The minimum length of a string property.

A string instance is valid against this property if its length is greater than, or equal to, the value of this
attribute.

See: JSON schema validation

maxItems : int|null

The maximum number of items allowed in an array property.

An array instance is valid against this property if its number of items is less than, or equal to, the value of
this attribute.

See: JSON schema validation

minItems : int|null

The minimum number of items allowed in an array property.

An array instance is valid against this property if its number of items is greater than, or equal to, the value
of this attribute.

See: JSON schema validation

uniqueItems : bool|null

A boolean value indicating whether all items in an array property must be unique.

If this attribute is set to true, then all items in the array must be unique.

See: JSON schema validation

pattern : string|null

A string instance is considered valid if the regular expression matches the instance successfully.

enum : array<string|int|float|bool|\\UnitEnum|null>|class-string|null

A collection of allowable values for a property.

A property instance is valid against this attribute if its value is one of the values specified in this
collection.

See: JSON schema validation

discriminator : OpenApi\\Attributes\\Discriminator|null

Adds support for polymorphism.

The discriminator is an object name that is used to differentiate between other schemas which may satisfy the
payload description. See Composition and Inheritance for more details.

readOnly : bool|null

Declares the property as "read only".

Relevant only for Schema "properties" definitions.

This means that it may be sent as part of a response but should not be sent as part of the request.
If the property is marked as readOnly being true and is in the required list, the required will take effect on
the response only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

writeOnly : bool|null

Declares the property as "write only".

Relevant only for Schema "properties" definitions.
Therefore, it may be sent as part of a request but should not be sent as part of the response.
If the property is marked as writeOnly being true and is in the required list, the required will take effect on
the request only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

xml : OpenApi\\Attributes\\Xml|null

This may be used only on properties schemas.

It has no effect on root schemas.
Adds additional metadata to describe the XML representation of this property.

externalDocs : OpenApi\\Attributes\\ExternalDocumentation|null

Additional external documentation for this schema.

example : mixed|null

A free-form property to include an example of an instance for this schema.

To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
contain the example with escaping where necessary.

nullable : bool|null

Allows sending a null value for the defined schema.
Default value is false.

This must not be used when using OpenApi version 3.1,
instead make the "type" property an array and add "null" as a possible type.

deprecated : bool|null

Specifies that a schema is deprecated and should be transitioned out of usage.
Default value is false.

allOf : array<Schema|\\OpenApi\\Annotations\\Schema>

An instance validates successfully against this property if it validates successfully against all schemas
defined by this property's value.

anyOf : array<Schema|\\OpenApi\\Annotations\\Schema>

An instance validates successfully against this property if it validates successfully against at least one
schema defined by this property's value.

oneOf : array<Schema|\\OpenApi\\Annotations\\Schema>

An instance validates successfully against this property if it validates successfully against exactly one schema
defined by this property's value.

additionalProperties : OpenApi\\Attributes\\AdditionalProperties|bool|null

http://json-schema.org/latest/json-schema-validation.html#anchor64.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

JsonContent

Nested elements

Discriminator, Items, Property, ExternalDocumentation, AdditionalProperties, Examples, Attachable

Parameters

examples : array<Examples>

Examples of the schema.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : string|null

The key into Components->schemas array.

title : string|null

Can be used to decorate a user interface with information about the data produced by this user interface.

Preferably short; use description for more details.

description : string|null

A description will provide explanation about the purpose of the instance described by this schema.

maxProperties : int|null

The maximum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is less than, or equal to, the
value of this attribute.

minProperties : int|null

The minimum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is greater than, or equal to, the
value of this attribute.

required : string[]

An object instance is valid against this property if its property set contains all elements in this property's
array value.

properties : Property[]

A collection of properties to define for an object.

Each property is represented as an instance of the Property class.

type : string|non-empty-array<string>|null

The type of the schema/property.

OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".

Since OpenApi v3.1 an array of types may be used.

format : string|null

The extending format for the previously mentioned type. See Data Type Formats for further details.

items : OpenApi\\Attributes\\Items|null

Required if type is "array". Describes the type of items in the array.

collectionFormat : string|null

Determines the format of the array if type array is used.

Possible values are:
- csv: comma separated values foo,bar.
- ssv: space separated values foo bar.
- tsv: tab separated values foo\\tbar.
- pipes: pipe separated values foo|bar.
- multi: corresponds to multiple parameter instances instead of multiple values for a single instance
foo=bar&foo=baz. This is valid only for parameters of type query or formData. Default
value is csv.

default : mixed|null

Sets a default value to the parameter. The type of the value depends on the defined type.

See: JSON schema validation

maximum : int|float

The maximum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMaximum : int|float|bool|null

A boolean indicating whether the maximum value is excluded from the set of valid values.

When set to true, the maximum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

minimum : int|float

The minimum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMinimum : int|float|bool|null

A boolean indicating whether the minimum value is excluded from the set of valid values.

When set to true, the minimum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

maxLength : int|null

The maximum length of a string property.

A string instance is valid against this property if its length is less than, or equal to, the value of this
attribute.

See: JSON schema validation

minLength : int|null

The minimum length of a string property.

A string instance is valid against this property if its length is greater than, or equal to, the value of this
attribute.

See: JSON schema validation

maxItems : int|null

The maximum number of items allowed in an array property.

An array instance is valid against this property if its number of items is less than, or equal to, the value of
this attribute.

See: JSON schema validation

minItems : int|null

The minimum number of items allowed in an array property.

An array instance is valid against this property if its number of items is greater than, or equal to, the value
of this attribute.

See: JSON schema validation

uniqueItems : bool|null

A boolean value indicating whether all items in an array property must be unique.

If this attribute is set to true, then all items in the array must be unique.

See: JSON schema validation

pattern : string|null

A string instance is considered valid if the regular expression matches the instance successfully.

enum : array<string|int|float|bool|\\UnitEnum|null>|class-string|null

A collection of allowable values for a property.

A property instance is valid against this attribute if its value is one of the values specified in this
collection.

See: JSON schema validation

discriminator : OpenApi\\Attributes\\Discriminator|null

Adds support for polymorphism.

The discriminator is an object name that is used to differentiate between other schemas which may satisfy the
payload description. See Composition and Inheritance for more details.

readOnly : bool|null

Declares the property as "read only".

Relevant only for Schema "properties" definitions.

This means that it may be sent as part of a response but should not be sent as part of the request.
If the property is marked as readOnly being true and is in the required list, the required will take effect on
the response only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

writeOnly : bool|null

Declares the property as "write only".

Relevant only for Schema "properties" definitions.
Therefore, it may be sent as part of a request but should not be sent as part of the response.
If the property is marked as writeOnly being true and is in the required list, the required will take effect on
the request only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

xml : OpenApi\\Attributes\\Xml|null

This may be used only on properties schemas.

It has no effect on root schemas.
Adds additional metadata to describe the XML representation of this property.

externalDocs : OpenApi\\Attributes\\ExternalDocumentation|null

Additional external documentation for this schema.

example : mixed|null

A free-form property to include an example of an instance for this schema.

To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
contain the example with escaping where necessary.

nullable : bool|null

Allows sending a null value for the defined schema.
Default value is false.

This must not be used when using OpenApi version 3.1,
instead make the "type" property an array and add "null" as a possible type.

deprecated : bool|null

Specifies that a schema is deprecated and should be transitioned out of usage.
Default value is false.

allOf : array<Schema|\\OpenApi\\Annotations\\Schema>

An instance validates successfully against this property if it validates successfully against all schemas
defined by this property's value.

anyOf : array<Schema|\\OpenApi\\Annotations\\Schema>

An instance validates successfully against this property if it validates successfully against at least one
schema defined by this property's value.

oneOf : array<Schema|\\OpenApi\\Annotations\\Schema>

An instance validates successfully against this property if it validates successfully against exactly one schema
defined by this property's value.

additionalProperties : OpenApi\\Attributes\\AdditionalProperties|bool|null

http://json-schema.org/latest/json-schema-validation.html#anchor64.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

License

Allowed in

Info

Nested elements

Attachable

Parameters

name : string|null

The license name used for the API.

identifier : string|null

An SPDX license expression for the API. The `identifier` field is mutually exclusive of the `url` field.

url : string|null

An URL to the license used for the API. This MUST be in the form of a URL.

The `url` field is mutually exclusive of the `identifier` field.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Allowed in

Components, Response

Nested elements

Server, Attachable

Parameters

link : string|null

The key into MediaType->links array.

operationRef : string|null

A relative or absolute reference to an OA operation.

This field is mutually exclusive of the operationId field, and must point to an Operation object.

Relative values may be used to locate an existing Operation object in the OpenAPI definition.

ref : string|class-string|object|null

No details available.

See: Using refs

operationId : string|null

The name of an existing, resolvable OA operation, as defined with a unique operationId.

This field is mutually exclusive of the operationRef field.

parameters : array<string,mixed>

A map representing parameters to pass to an operation as specified with operationId or identified via
operationRef.

The key is the parameter name to be used, whereas the value can be a constant or an expression to
be evaluated and passed to the linked operation.
The parameter name can be qualified using the parameter location [{in}.]{name} for operations
that use the same parameter name in different locations (e.g. path.id).

requestBody : mixed|null

A literal value or {expression} to use as a request body when calling the target operation.

description : string|null

A description of the link.

CommonMark syntax may be used for rich text representation.

server : OpenApi\\Attributes\\Server|null

A server object to be used by the target operation.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

MediaType

Allowed in

Response, RequestBody

Nested elements

Schema, Examples, Attachable

Parameters

mediaType : string|null

The key into Operation->content array.

schema : OpenApi\\Attributes\\Schema|null

The schema defining the type used for the request body.

example : mixed|null

Example of the media type.

The example object should be in the correct format as specified by the media type.
The example object is mutually exclusive of the examples object.

Furthermore, if referencing a schema which contains an example,
the example value shall override the example provided by the schema.

examples : array<Examples>

Examples of the media type.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

encoding : array<string,mixed>

A map between a property name and its encoding information.

The key, being the property name, must exist in the schema as a property.

The encoding object shall only apply to requestBody objects when the media type is multipart or
application/x-www-form-urlencoded.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

OpenApi

Nested elements

Info, Server, PathItem, Components, Tag, ExternalDocumentation, Webhook, Attachable

Parameters

openapi : string

The semantic version number of the OpenAPI Specification version that the OpenAPI document uses.

The openapi field should be used by tooling specifications and clients to interpret the OpenAPI document.

A version specified via `Generator::setVersion()` will overwrite this value.

This is not related to the API info::version string.

info : OpenApi\\Attributes\\Info|null

Provides metadata about the API. The metadata may be used by tooling as required.

servers : Server[]|null

An array of @Server objects, which provide connectivity information to a target server.

If not provided, or is an empty array, the default value would be a Server Object with an url value of /.

security : array|null

A declaration of which security mechanisms can be used across the API.

The list of values includes alternative security requirement objects that can be used.
Only one of the security requirement objects need to be satisfied to authorize a request.
Individual operations can override this definition.
To make security optional, an empty security requirement `({})` can be included in the array.

tags : Tag[]|null

A list of tags used by the specification with additional metadata.

The order of the tags can be used to reflect on their order by the parsing tools.
Not all tags that are used by the Operation Object must be declared.
The tags that are not declared may be organized randomly or based on the tools' logic.
Each tag name in the list must be unique.

externalDocs : OpenApi\\Attributes\\ExternalDocumentation|null

Additional external documentation.

paths : PathItem[]|null

The available paths and operations for the API.

components : OpenApi\\Attributes\\Components|null

An element to hold various components for the specification.

webhooks : Webhook[]|null

The available webhooks for the API.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Options

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters

path : string|null

Key in the OpenApi "Paths Object" for this operation.

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

summary : string|null

A short summary of what the operation does.

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

requestBody : OpenApi\\Attributes\\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

responses : Response[]

The list of possible responses as they are returned from executing this operation.

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

externalDocs : OpenApi\\Attributes\\ExternalDocumentation|null

Additional external documentation for this operation.

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Parameter

Allowed in

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements

Schema, Examples, Attachable

Parameters

parameter : string|null

The key into Components::parameters or PathItem::parameters array.

name : string|null

The (case-sensitive) name of the parameter.

If in is "path", the name field must correspond to the associated path segment from the path field in the Paths Object.

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition shall be ignored.
For all other cases, the name corresponds to the parameter name used by the in property.

description : string|null

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

in : string|null

The location of the parameter.

Possible values are "query", "header", "path" or "cookie".

required : bool|null

Determines whether this parameter is mandatory.

If the parameter location is "path", this property is required and its value must be true.
Otherwise, the property may be included and its default value is false.

deprecated : bool|null

Specifies that a parameter is deprecated and should be transitioned out of usage.

allowEmptyValue : bool|null

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue shall be ignored.

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : OpenApi\\Attributes\\Schema|null

The schema defining the type used for the parameter.

example : mixed|null

Example of the media type.

The example should match the specified schema and encoding properties if present.
The example object is mutually exclusive of the examples object.
Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema.
To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

examples : array<Examples>

Examples of the parameter.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

content : array<MediaType>|JsonContent|XmlContent|Attachable|null

A map containing the representations for the parameter.

The key is the media type and the value describes it.
The map must only contain one entry.

style : string|null

Describes how the parameter value will be serialized depending on the type of the parameter value.

Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

explode : bool|null

When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.

For other types of parameters this property has no effect.

When style is form, the default value is true.
For all other styles, the default value is false.

allowReserved : bool|null

Determines whether the parameter value should allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.

This property only applies to parameters with an in value of query.

The default value is false.

spaceDelimited : array|null

Space separated array values.

This option replaces collectionFormat equal to ssv from OpenAPI 2.0.

pipeDelimited : array|null

Pipe separated array values.

This option replaces collectionFormat equal to pipes from OpenAPI 2.0.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Patch

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters

path : string|null

Key in the OpenApi "Paths Object" for this operation.

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

summary : string|null

A short summary of what the operation does.

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

requestBody : OpenApi\\Attributes\\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

responses : Response[]

The list of possible responses as they are returned from executing this operation.

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

externalDocs : OpenApi\\Attributes\\ExternalDocumentation|null

Additional external documentation for this operation.

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

PathItem

Allowed in

OpenApi

Nested elements

Get, Post, Put, Delete, Patch, Trace, Head, Options, Parameter, PathParameter, Server, Attachable

Parameters

path : string|null

Key for the Path Object (OpenApi->paths array).

ref : string|class-string|object|null

No details available.

See: Using refs

summary : string|null

An optional, string summary, intended to apply to all operations in this path.

description : string|null

An optional, string description, intended to apply to all operations in this path.

get : OpenApi\\Attributes\\Get|null

A definition of a GET operation on this path.

put : OpenApi\\Attributes\\Put|null

A definition of a PUT operation on this path.

post : OpenApi\\Attributes\\Post|null

A definition of a POST operation on this path.

delete : OpenApi\\Attributes\\Delete|null

A definition of a DELETE operation on this path.

options : OpenApi\\Attributes\\Options|null

A definition of a OPTIONS operation on this path.

head : OpenApi\\Attributes\\Head|null

A definition of a HEAD operation on this path.

patch : OpenApi\\Attributes\\Patch|null

A definition of a PATCH operation on this path.

trace : OpenApi\\Attributes\\Trace|null

A definition of a TRACE operation on this path.

servers : Server[]|null

An alternative server array to service all operations in this path.

parameters : Parameter[]|null

A list of parameters that are applicable for all the operations described under this path.

These parameters can be overridden at the operation level, but cannot be removed there.
The list must not include duplicated parameters.
A unique parameter is defined by a combination of a name and location.
The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's components/parameters.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

PathParameter

Allowed in

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements

Schema, Examples, Attachable

Parameters

parameter : string|null

The key into Components::parameters or PathItem::parameters array.

name : string|null

The (case-sensitive) name of the parameter.

If in is "path", the name field must correspond to the associated path segment from the path field in the Paths Object.

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition shall be ignored.
For all other cases, the name corresponds to the parameter name used by the in property.

description : string|null

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

in : string|null

This takes 'path' as the default location.

required : bool|null

No details available.

deprecated : bool|null

Specifies that a parameter is deprecated and should be transitioned out of usage.

allowEmptyValue : bool|null

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue shall be ignored.

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : OpenApi\\Attributes\\Schema|null

The schema defining the type used for the parameter.

example : mixed|null

Example of the media type.

The example should match the specified schema and encoding properties if present.
The example object is mutually exclusive of the examples object.
Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema.
To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

examples : array<Examples>

Examples of the parameter.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

content : array<MediaType>|JsonContent|XmlContent|Attachable|null

A map containing the representations for the parameter.

The key is the media type and the value describes it.
The map must only contain one entry.

style : string|null

Describes how the parameter value will be serialized depending on the type of the parameter value.

Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

explode : bool|null

When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.

For other types of parameters this property has no effect.

When style is form, the default value is true.
For all other styles, the default value is false.

allowReserved : bool|null

Determines whether the parameter value should allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.

This property only applies to parameters with an in value of query.

The default value is false.

spaceDelimited : array|null

Space separated array values.

This option replaces collectionFormat equal to ssv from OpenAPI 2.0.

pipeDelimited : array|null

Pipe separated array values.

This option replaces collectionFormat equal to pipes from OpenAPI 2.0.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Post

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters

path : string|null

Key in the OpenApi "Paths Object" for this operation.

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

summary : string|null

A short summary of what the operation does.

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

requestBody : OpenApi\\Attributes\\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

responses : Response[]

The list of possible responses as they are returned from executing this operation.

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

externalDocs : OpenApi\\Attributes\\ExternalDocumentation|null

Additional external documentation for this operation.

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Property

Allowed in

AdditionalProperties, Schema, JsonContent, XmlContent, Property, Items

Nested elements

Discriminator, Items, Property, ExternalDocumentation, Xml, AdditionalProperties, Attachable

Parameters

property : string|null

The key into Schema->properties array.

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : string|null

The key into Components->schemas array.

title : string|null

Can be used to decorate a user interface with information about the data produced by this user interface.

Preferably short; use description for more details.

description : string|null

A description will provide explanation about the purpose of the instance described by this schema.

maxProperties : int|null

The maximum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is less than, or equal to, the
value of this attribute.

minProperties : int|null

The minimum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is greater than, or equal to, the
value of this attribute.

required : string[]

An object instance is valid against this property if its property set contains all elements in this property's
array value.

properties : Property[]

A collection of properties to define for an object.

Each property is represented as an instance of the Property class.

type : string|non-empty-array<string>|null

The type of the schema/property.

OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".

Since OpenApi v3.1 an array of types may be used.

format : string|null

The extending format for the previously mentioned type. See Data Type Formats for further details.

items : OpenApi\\Attributes\\Items|null

Required if type is "array". Describes the type of items in the array.

collectionFormat : string|null

Determines the format of the array if type array is used.

Possible values are:
- csv: comma separated values foo,bar.
- ssv: space separated values foo bar.
- tsv: tab separated values foo\\tbar.
- pipes: pipe separated values foo|bar.
- multi: corresponds to multiple parameter instances instead of multiple values for a single instance
foo=bar&foo=baz. This is valid only for parameters of type query or formData. Default
value is csv.

default : mixed|null

Sets a default value to the parameter. The type of the value depends on the defined type.

See: JSON schema validation

maximum : int|float

The maximum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMaximum : int|float|bool|null

A boolean indicating whether the maximum value is excluded from the set of valid values.

When set to true, the maximum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

minimum : int|float

The minimum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMinimum : int|float|bool|null

A boolean indicating whether the minimum value is excluded from the set of valid values.

When set to true, the minimum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

maxLength : int|null

The maximum length of a string property.

A string instance is valid against this property if its length is less than, or equal to, the value of this
attribute.

See: JSON schema validation

minLength : int|null

The minimum length of a string property.

A string instance is valid against this property if its length is greater than, or equal to, the value of this
attribute.

See: JSON schema validation

maxItems : int|null

The maximum number of items allowed in an array property.

An array instance is valid against this property if its number of items is less than, or equal to, the value of
this attribute.

See: JSON schema validation

minItems : int|null

The minimum number of items allowed in an array property.

An array instance is valid against this property if its number of items is greater than, or equal to, the value
of this attribute.

See: JSON schema validation

uniqueItems : bool|null

A boolean value indicating whether all items in an array property must be unique.

If this attribute is set to true, then all items in the array must be unique.

See: JSON schema validation

pattern : string|null

A string instance is considered valid if the regular expression matches the instance successfully.

enum : array<string|int|float|bool|\\UnitEnum|null>|class-string|null

A collection of allowable values for a property.

A property instance is valid against this attribute if its value is one of the values specified in this
collection.

See: JSON schema validation

discriminator : OpenApi\\Attributes\\Discriminator|null

Adds support for polymorphism.

The discriminator is an object name that is used to differentiate between other schemas which may satisfy the
payload description. See Composition and Inheritance for more details.

readOnly : bool|null

Declares the property as "read only".

Relevant only for Schema "properties" definitions.

This means that it may be sent as part of a response but should not be sent as part of the request.
If the property is marked as readOnly being true and is in the required list, the required will take effect on
the response only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

writeOnly : bool|null

Declares the property as "write only".

Relevant only for Schema "properties" definitions.
Therefore, it may be sent as part of a request but should not be sent as part of the response.
If the property is marked as writeOnly being true and is in the required list, the required will take effect on
the request only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

xml : OpenApi\\Attributes\\Xml|null

This may be used only on properties schemas.

It has no effect on root schemas.
Adds additional metadata to describe the XML representation of this property.

externalDocs : OpenApi\\Attributes\\ExternalDocumentation|null

Additional external documentation for this schema.

example : mixed|null

A free-form property to include an example of an instance for this schema.

To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
contain the example with escaping where necessary.

nullable : bool|null

Allows sending a null value for the defined schema.
Default value is false.

This must not be used when using OpenApi version 3.1,
instead make the "type" property an array and add "null" as a possible type.

deprecated : bool|null

Specifies that a schema is deprecated and should be transitioned out of usage.
Default value is false.

allOf : array<Schema|\\OpenApi\\Annotations\\Schema>

An instance validates successfully against this property if it validates successfully against all schemas
defined by this property's value.

anyOf : array<Schema|\\OpenApi\\Annotations\\Schema>

An instance validates successfully against this property if it validates successfully against at least one
schema defined by this property's value.

oneOf : array<Schema|\\OpenApi\\Annotations\\Schema>

An instance validates successfully against this property if it validates successfully against exactly one schema
defined by this property's value.

additionalProperties : OpenApi\\Attributes\\AdditionalProperties|bool|null

http://json-schema.org/latest/json-schema-validation.html#anchor64.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Put

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters

path : string|null

Key in the OpenApi "Paths Object" for this operation.

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

summary : string|null

A short summary of what the operation does.

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

requestBody : OpenApi\\Attributes\\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

responses : Response[]

The list of possible responses as they are returned from executing this operation.

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

externalDocs : OpenApi\\Attributes\\ExternalDocumentation|null

Additional external documentation for this operation.

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

QueryParameter

Allowed in

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements

Schema, Examples, Attachable

Parameters

parameter : string|null

The key into Components::parameters or PathItem::parameters array.

name : string|null

The (case-sensitive) name of the parameter.

If in is "path", the name field must correspond to the associated path segment from the path field in the Paths Object.

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition shall be ignored.
For all other cases, the name corresponds to the parameter name used by the in property.

description : string|null

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

in : string|null

This takes 'query' as the default location.

required : bool|null

Determines whether this parameter is mandatory.

If the parameter location is "path", this property is required and its value must be true.
Otherwise, the property may be included and its default value is false.

deprecated : bool|null

Specifies that a parameter is deprecated and should be transitioned out of usage.

allowEmptyValue : bool|null

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue shall be ignored.

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : OpenApi\\Attributes\\Schema|null

The schema defining the type used for the parameter.

example : mixed|null

Example of the media type.

The example should match the specified schema and encoding properties if present.
The example object is mutually exclusive of the examples object.
Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema.
To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

examples : array<Examples>

Examples of the parameter.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

content : array<MediaType>|JsonContent|XmlContent|Attachable|null

A map containing the representations for the parameter.

The key is the media type and the value describes it.
The map must only contain one entry.

style : string|null

Describes how the parameter value will be serialized depending on the type of the parameter value.

Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

explode : bool|null

When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.

For other types of parameters this property has no effect.

When style is form, the default value is true.
For all other styles, the default value is false.

allowReserved : bool|null

Determines whether the parameter value should allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.

This property only applies to parameters with an in value of query.

The default value is false.

spaceDelimited : array|null

Space separated array values.

This option replaces collectionFormat equal to ssv from OpenAPI 2.0.

pipeDelimited : array|null

Pipe separated array values.

This option replaces collectionFormat equal to pipes from OpenAPI 2.0.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

RequestBody

Allowed in

Components, Delete, Get, Head, Operation, Options, Patch, Post, Trace, Put

Nested elements

MediaType, Attachable

Parameters

ref : string|class-string|object|null

The relative or absolute path to a request body.

See: Using refs

request : string|null

The key into Components->requestBodies array.

description : string|null

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

required : bool|null

Determines whether this parameter is mandatory.

If the parameter location is "path", this property is required and its value must be true.
Otherwise, the property may be included and its default value is false.

content : array<MediaType|JsonContent|XmlContent>|MediaType|XmlContent|Attachable|null

The content of the request body.

The key is a media type or media type range and the value describes it. For requests that match multiple keys,
only the most specific key is applicable. e.g. text/plain overrides text/*.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Response

Allowed in

Components, Operation, Get, Post, Put, Patch, Delete, Head, Options, Trace

Nested elements

MediaType, Header, Link, Attachable

Parameters

ref : string|class-string|object|null

The relative or absolute path to a response.

See: Using refs

response : string|int|null

The key into Operations->responses array.

A HTTP status code or default.

description : string|null

A short description of the response.

CommonMark syntax may be used for rich text representation.

headers : Header[]

Maps a header name to its definition.

RFC7230 states header names are case insensitive.

If a response header is defined with the name "Content-Type", it shall be ignored.

See: RFC7230

content : MediaType|JsonContent|XmlContent|Attachable|array<MediaType|Attachable>

A map containing descriptions of potential response payloads.

The key is a media type or media type range and the value describes it.

For responses that match multiple keys, only the most specific key is applicable;
e.g. text/plain overrides text/*.

links : Link[]

A map of operations links that can be followed from the response.

The key of the map is a short name for the link, following the naming constraints of the names for Component
Objects.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Schema

Allowed in

Components, Parameter, PathParameter, MediaType, Header

Nested elements

Discriminator, Items, Property, ExternalDocumentation, Examples, Xml, AdditionalProperties, Attachable

Parameters

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : string|null

The key into Components->schemas array.

title : string|null

Can be used to decorate a user interface with information about the data produced by this user interface.

Preferably short; use description for more details.

description : string|null

A description will provide explanation about the purpose of the instance described by this schema.

maxProperties : int|null

The maximum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is less than, or equal to, the
value of this attribute.

minProperties : int|null

The minimum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is greater than, or equal to, the
value of this attribute.

required : string[]

An object instance is valid against this property if its property set contains all elements in this property's
array value.

properties : Property[]

A collection of properties to define for an object.

Each property is represented as an instance of the Property class.

type : string|non-empty-array<string>|null

The type of the schema/property.

OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".

Since OpenApi v3.1 an array of types may be used.

format : string|null

The extending format for the previously mentioned type. See Data Type Formats for further details.

items : OpenApi\\Attributes\\Items|null

Required if type is "array". Describes the type of items in the array.

collectionFormat : string|null

Determines the format of the array if type array is used.

Possible values are:
- csv: comma separated values foo,bar.
- ssv: space separated values foo bar.
- tsv: tab separated values foo\\tbar.
- pipes: pipe separated values foo|bar.
- multi: corresponds to multiple parameter instances instead of multiple values for a single instance
foo=bar&foo=baz. This is valid only for parameters of type query or formData. Default
value is csv.

default : mixed|null

Sets a default value to the parameter. The type of the value depends on the defined type.

See: JSON schema validation

maximum : int|float

The maximum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMaximum : int|float|bool|null

A boolean indicating whether the maximum value is excluded from the set of valid values.

When set to true, the maximum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

minimum : int|float

The minimum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMinimum : int|float|bool|null

A boolean indicating whether the minimum value is excluded from the set of valid values.

When set to true, the minimum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

maxLength : int|null

The maximum length of a string property.

A string instance is valid against this property if its length is less than, or equal to, the value of this
attribute.

See: JSON schema validation

minLength : int|null

The minimum length of a string property.

A string instance is valid against this property if its length is greater than, or equal to, the value of this
attribute.

See: JSON schema validation

maxItems : int|null

The maximum number of items allowed in an array property.

An array instance is valid against this property if its number of items is less than, or equal to, the value of
this attribute.

See: JSON schema validation

minItems : int|null

The minimum number of items allowed in an array property.

An array instance is valid against this property if its number of items is greater than, or equal to, the value
of this attribute.

See: JSON schema validation

uniqueItems : bool|null

A boolean value indicating whether all items in an array property must be unique.

If this attribute is set to true, then all items in the array must be unique.

See: JSON schema validation

pattern : string|null

A string instance is considered valid if the regular expression matches the instance successfully.

enum : array<string|int|float|bool|\\UnitEnum|null>|class-string|null

A collection of allowable values for a property.

A property instance is valid against this attribute if its value is one of the values specified in this
collection.

See: JSON schema validation

discriminator : OpenApi\\Attributes\\Discriminator|null

Adds support for polymorphism.

The discriminator is an object name that is used to differentiate between other schemas which may satisfy the
payload description. See Composition and Inheritance for more details.

readOnly : bool|null

Declares the property as "read only".

Relevant only for Schema "properties" definitions.

This means that it may be sent as part of a response but should not be sent as part of the request.
If the property is marked as readOnly being true and is in the required list, the required will take effect on
the response only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

writeOnly : bool|null

Declares the property as "write only".

Relevant only for Schema "properties" definitions.
Therefore, it may be sent as part of a request but should not be sent as part of the response.
If the property is marked as writeOnly being true and is in the required list, the required will take effect on
the request only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

xml : OpenApi\\Attributes\\Xml|null

This may be used only on properties schemas.

It has no effect on root schemas.
Adds additional metadata to describe the XML representation of this property.

externalDocs : OpenApi\\Attributes\\ExternalDocumentation|null

Additional external documentation for this schema.

example : mixed|null

A free-form property to include an example of an instance for this schema.

To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
contain the example with escaping where necessary.

examples : array<Examples>

Examples of the schema.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

nullable : bool|null

Allows sending a null value for the defined schema.
Default value is false.

This must not be used when using OpenApi version 3.1,
instead make the "type" property an array and add "null" as a possible type.

deprecated : bool|null

Specifies that a schema is deprecated and should be transitioned out of usage.
Default value is false.

allOf : array<Schema|\\OpenApi\\Annotations\\Schema>

An instance validates successfully against this property if it validates successfully against all schemas
defined by this property's value.

anyOf : array<Schema|\\OpenApi\\Annotations\\Schema>

An instance validates successfully against this property if it validates successfully against at least one
schema defined by this property's value.

oneOf : array<Schema|\\OpenApi\\Annotations\\Schema>

An instance validates successfully against this property if it validates successfully against exactly one schema
defined by this property's value.

additionalProperties : OpenApi\\Attributes\\AdditionalProperties|bool|null

http://json-schema.org/latest/json-schema-validation.html#anchor64.

const : mixed|null

http://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.1.3.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

SecurityScheme

Allowed in

Components

Nested elements

Flow, Attachable

Parameters

ref : string|class-string|object|null

The relative or absolute path to a security scheme.

See: Using refs

securityScheme : string|null

The key into OpenApi->security array.

type : string|non-empty-array<string>|null

The type of the security scheme.

description : string|null

A short description for security scheme.

name : string|null

The name of the header or query parameter to be used.

in : string|null

Required The location of the API key.

bearerFormat : string|null

A hint to the client to identify how the bearer token is formatted.

Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.

scheme : string|null

The name of the HTTP Authorization scheme.

See: RFC7235

openIdConnectUrl : string|null

OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL.

flows : Flow[]

The flow used by the OAuth2 security scheme.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Server

Allowed in

OpenApi, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace, Link

Nested elements

ServerVariable, Attachable

Parameters

url : string|null

An URL to the target host.

This URL supports Server Variables and may be relative,
to indicate that the host location is relative to the location where the OpenAPI document is being served.
Variable substitutions will be made when a variable is named in {brackets}.

description : string|null

An optional string describing the host designated by the URL.

CommonMark syntax may be used for rich text representation.

variables : ServerVariable[]

A map between a variable name and its value.

The value is used for substitution in the server's URL template.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

ServerVariable

Allowed in

Server

Nested elements

Attachable

Parameters

serverVariable : string|null

The key into Server->variables array.

description : string|null

An optional description for the server variable.

CommonMark syntax MAY be used for rich text representation.

default : string|null

The default value to use for substitution, and to send, if an alternate value is not supplied.

Unlike the Schema Object's default, this value must be provided by the consumer.

enum : array<string|int|float|bool|\\UnitEnum|null>|class-string|null

An enumeration of values to be used if the substitution options are from a limited set.

variables : array|null

A map between a variable name and its value.

The value is used for substitution in the server's URL template.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Tag

Allowed in

OpenApi

Nested elements

ExternalDocumentation, Attachable

Parameters

name : string|null

The name of the tag.

description : string|null

A short description for the tag. GFM syntax can be used for rich text representation.

externalDocs : OpenApi\\Attributes\\ExternalDocumentation|null

Additional external documentation for this tag.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Trace

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters

path : string|null

Key in the OpenApi "Paths Object" for this operation.

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

summary : string|null

A short summary of what the operation does.

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

requestBody : OpenApi\\Attributes\\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

responses : Response[]

The list of possible responses as they are returned from executing this operation.

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

externalDocs : OpenApi\\Attributes\\ExternalDocumentation|null

Additional external documentation for this operation.

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Webhook

Allowed in

OpenApi

Nested elements

Get, Post, Put, Delete, Patch, Trace, Head, Options, Parameter, PathParameter, Server, Attachable

Parameters

webhook : string|null

Key for the webhooks map.

path : string|null

Key for the Path Object (OpenApi->paths array).

ref : string|class-string|object|null

No details available.

See: Using refs

summary : string|null

An optional, string summary, intended to apply to all operations in this path.

description : string|null

An optional, string description, intended to apply to all operations in this path.

get : OpenApi\\Attributes\\Get|null

A definition of a GET operation on this path.

put : OpenApi\\Attributes\\Put|null

A definition of a PUT operation on this path.

post : OpenApi\\Attributes\\Post|null

A definition of a POST operation on this path.

delete : OpenApi\\Attributes\\Delete|null

A definition of a DELETE operation on this path.

options : OpenApi\\Attributes\\Options|null

A definition of a OPTIONS operation on this path.

head : OpenApi\\Attributes\\Head|null

A definition of a HEAD operation on this path.

patch : OpenApi\\Attributes\\Patch|null

A definition of a PATCH operation on this path.

trace : OpenApi\\Attributes\\Trace|null

A definition of a TRACE operation on this path.

servers : Server[]|null

An alternative server array to service all operations in this path.

parameters : Parameter[]|null

A list of parameters that are applicable for all the operations described under this path.

These parameters can be overridden at the operation level, but cannot be removed there.
The list must not include duplicated parameters.
A unique parameter is defined by a combination of a name and location.
The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's components/parameters.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Xml

Allowed in

AdditionalProperties, Schema, Property, Schema, Items, XmlContent

Nested elements

Attachable

Parameters

name : string|null

Replaces the name of the element/attribute used for the described schema property.

When defined within the Items Object (items), it will affect the name of the individual XML elements within the list.
When defined alongside type being array (outside the items), it will affect the wrapping element
and only if wrapped is true.

If wrapped is false, it will be ignored.

namespace : string|null

The URL of the namespace definition. Value SHOULD be in the form of a URL.

prefix : string|null

The prefix to be used for the name.

attribute : bool|null

Declares whether the property definition translates to an attribute instead of an element.

Default value is false.

wrapped : bool|null

MAY be used only for an array definition.

Signifies whether the array is wrapped (for example <books><book/><book/></books>)
or unwrapped (<book/><book/>).

Default value is false. The definition takes effect only when defined alongside type being array (outside the items).

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

XmlContent

Nested elements

Discriminator, Items, Property, ExternalDocumentation, Xml, AdditionalProperties, Examples, Attachable

Parameters

examples : array<Examples>

Examples of the schema.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : string|null

The key into Components->schemas array.

title : string|null

Can be used to decorate a user interface with information about the data produced by this user interface.

Preferably short; use description for more details.

description : string|null

A description will provide explanation about the purpose of the instance described by this schema.

maxProperties : int|null

The maximum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is less than, or equal to, the
value of this attribute.

minProperties : int|null

The minimum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is greater than, or equal to, the
value of this attribute.

required : string[]

An object instance is valid against this property if its property set contains all elements in this property's
array value.

properties : Property[]

A collection of properties to define for an object.

Each property is represented as an instance of the Property class.

type : string|non-empty-array<string>|null

The type of the schema/property.

OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".

Since OpenApi v3.1 an array of types may be used.

format : string|null

The extending format for the previously mentioned type. See Data Type Formats for further details.

items : OpenApi\\Attributes\\Items|null

Required if type is "array". Describes the type of items in the array.

collectionFormat : string|null

Determines the format of the array if type array is used.

Possible values are:
- csv: comma separated values foo,bar.
- ssv: space separated values foo bar.
- tsv: tab separated values foo\\tbar.
- pipes: pipe separated values foo|bar.
- multi: corresponds to multiple parameter instances instead of multiple values for a single instance
foo=bar&foo=baz. This is valid only for parameters of type query or formData. Default
value is csv.

default : mixed|null

Sets a default value to the parameter. The type of the value depends on the defined type.

See: JSON schema validation

maximum : int|float

The maximum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMaximum : int|float|bool|null

A boolean indicating whether the maximum value is excluded from the set of valid values.

When set to true, the maximum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

minimum : int|float

The minimum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMinimum : int|float|bool|null

A boolean indicating whether the minimum value is excluded from the set of valid values.

When set to true, the minimum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

maxLength : int|null

The maximum length of a string property.

A string instance is valid against this property if its length is less than, or equal to, the value of this
attribute.

See: JSON schema validation

minLength : int|null

The minimum length of a string property.

A string instance is valid against this property if its length is greater than, or equal to, the value of this
attribute.

See: JSON schema validation

maxItems : int|null

The maximum number of items allowed in an array property.

An array instance is valid against this property if its number of items is less than, or equal to, the value of
this attribute.

See: JSON schema validation

minItems : int|null

The minimum number of items allowed in an array property.

An array instance is valid against this property if its number of items is greater than, or equal to, the value
of this attribute.

See: JSON schema validation

uniqueItems : bool|null

A boolean value indicating whether all items in an array property must be unique.

If this attribute is set to true, then all items in the array must be unique.

See: JSON schema validation

pattern : string|null

A string instance is considered valid if the regular expression matches the instance successfully.

enum : array<string|int|float|bool|\\UnitEnum|null>|class-string|null

A collection of allowable values for a property.

A property instance is valid against this attribute if its value is one of the values specified in this
collection.

See: JSON schema validation

discriminator : OpenApi\\Attributes\\Discriminator|null

Adds support for polymorphism.

The discriminator is an object name that is used to differentiate between other schemas which may satisfy the
payload description. See Composition and Inheritance for more details.

readOnly : bool|null

Declares the property as "read only".

Relevant only for Schema "properties" definitions.

This means that it may be sent as part of a response but should not be sent as part of the request.
If the property is marked as readOnly being true and is in the required list, the required will take effect on
the response only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

writeOnly : bool|null

Declares the property as "write only".

Relevant only for Schema "properties" definitions.
Therefore, it may be sent as part of a request but should not be sent as part of the response.
If the property is marked as writeOnly being true and is in the required list, the required will take effect on
the request only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

xml : OpenApi\\Attributes\\Xml|null

This may be used only on properties schemas.

It has no effect on root schemas.
Adds additional metadata to describe the XML representation of this property.

externalDocs : OpenApi\\Attributes\\ExternalDocumentation|null

Additional external documentation for this schema.

example : mixed|null

A free-form property to include an example of an instance for this schema.

To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
contain the example with escaping where necessary.

nullable : bool|null

Allows sending a null value for the defined schema.
Default value is false.

This must not be used when using OpenApi version 3.1,
instead make the "type" property an array and add "null" as a possible type.

deprecated : bool|null

Specifies that a schema is deprecated and should be transitioned out of usage.
Default value is false.

allOf : array<Schema|\\OpenApi\\Annotations\\Schema>

An instance validates successfully against this property if it validates successfully against all schemas
defined by this property's value.

anyOf : array<Schema|\\OpenApi\\Annotations\\Schema>

An instance validates successfully against this property if it validates successfully against at least one
schema defined by this property's value.

oneOf : array<Schema|\\OpenApi\\Annotations\\Schema>

An instance validates successfully against this property if it validates successfully against exactly one schema
defined by this property's value.

additionalProperties : OpenApi\\Attributes\\AdditionalProperties|bool|null

http://json-schema.org/latest/json-schema-validation.html#anchor64.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

',402),o=[r];function i(d,l,p,h,c,m){return a(),t("div",null,o)}var b=e(s,[["render",i]]);export{u as __pageData,b as default}; diff --git a/assets/reference_attributes.md.e96acd84.lean.js b/assets/reference_attributes.md.e96acd84.lean.js new file mode 100644 index 000000000..649e7ec6e --- /dev/null +++ b/assets/reference_attributes.md.e96acd84.lean.js @@ -0,0 +1 @@ +import{_ as e,c as t,o as a,a as n}from"./app.d3800f98.js";const u='{"title":"Attributes","description":"","frontmatter":{},"headers":[{"level":2,"title":"AdditionalProperties","slug":"additionalproperties"},{"level":2,"title":"Attachable","slug":"attachable"},{"level":2,"title":"Components","slug":"components"},{"level":2,"title":"Contact","slug":"contact"},{"level":2,"title":"CookieParameter","slug":"cookieparameter"},{"level":2,"title":"Delete","slug":"delete"},{"level":2,"title":"Discriminator","slug":"discriminator"},{"level":2,"title":"Examples","slug":"examples"},{"level":2,"title":"ExternalDocumentation","slug":"externaldocumentation"},{"level":2,"title":"Flow","slug":"flow"},{"level":2,"title":"Get","slug":"get"},{"level":2,"title":"Head","slug":"head"},{"level":2,"title":"Header","slug":"header"},{"level":2,"title":"HeaderParameter","slug":"headerparameter"},{"level":2,"title":"Info","slug":"info"},{"level":2,"title":"Items","slug":"items"},{"level":2,"title":"JsonContent","slug":"jsoncontent"},{"level":2,"title":"License","slug":"license"},{"level":2,"title":"Link","slug":"link"},{"level":2,"title":"MediaType","slug":"mediatype"},{"level":2,"title":"OpenApi","slug":"openapi"},{"level":2,"title":"Options","slug":"options"},{"level":2,"title":"Parameter","slug":"parameter"},{"level":2,"title":"Patch","slug":"patch"},{"level":2,"title":"PathItem","slug":"pathitem"},{"level":2,"title":"PathParameter","slug":"pathparameter"},{"level":2,"title":"Post","slug":"post"},{"level":2,"title":"Property","slug":"property"},{"level":2,"title":"Put","slug":"put"},{"level":2,"title":"QueryParameter","slug":"queryparameter"},{"level":2,"title":"RequestBody","slug":"requestbody"},{"level":2,"title":"Response","slug":"response"},{"level":2,"title":"Schema","slug":"schema"},{"level":2,"title":"SecurityScheme","slug":"securityscheme"},{"level":2,"title":"Server","slug":"server"},{"level":2,"title":"ServerVariable","slug":"servervariable"},{"level":2,"title":"Tag","slug":"tag"},{"level":2,"title":"Trace","slug":"trace"},{"level":2,"title":"Webhook","slug":"webhook"},{"level":2,"title":"Xml","slug":"xml"},{"level":2,"title":"XmlContent","slug":"xmlcontent"}],"relativePath":"reference/attributes.md"}',s={},r=n("",402),o=[r];function i(d,l,p,h,c,m){return a(),t("div",null,o)}var b=e(s,[["render",i]]);export{u as __pageData,b as default}; diff --git a/assets/reference_generator.md.681f1e2d.js b/assets/reference_generator.md.681f1e2d.js new file mode 100644 index 000000000..a9b0c4331 --- /dev/null +++ b/assets/reference_generator.md.681f1e2d.js @@ -0,0 +1,80 @@ +import{_ as n,c as s,o as a,a as t}from"./app.d3800f98.js";const h='{"title":"Using the Generator","description":"","frontmatter":{},"headers":[{"level":2,"title":"Introduction","slug":"introduction"},{"level":2,"title":"The \\\\OpenApi\\\\scan() function","slug":"the-openapi-scan-function"},{"level":2,"title":"The \\\\OpenApi\\\\Generator class","slug":"the-openapi-generator-class"}],"relativePath":"reference/generator.md"}',e={},p=t(`

Using the Generator

Introduction

The Generator class provides an object-oriented way to use swagger-php and all its aspects in a single place.

The \\OpenApi\\scan() function

For a long time the \\OpenApi\\scan() function was the main entry point into using swagger-php from PHP code.

/**
+  * Scan the filesystem for OpenAPI annotations and build openapi-documentation.
+  *
+  * @param array|Finder|string $directory The directory(s) or filename(s)
+  * @param array               $options
+  *                                       exclude: string|array $exclude The directory(s) or filename(s) to exclude (as absolute or relative paths)
+  *                                       pattern: string       $pattern File pattern(s) to scan (default: *.php)
+  *                                       analyser: defaults to StaticAnalyser
+  *                                       analysis: defaults to a new Analysis
+  *                                       processors: defaults to the registered processors in Analysis
+  *
+  * @return OpenApi
+  */
+  function scan($directory, $options = []) { /* ... */ }
+

Using it looked typically something like this:

require("vendor/autoload.php");
+
+$openapi = \\OpenApi\\scan(__DIR__, ['exclude' => ['tests'], 'pattern' => '*.php']);
+

The two configuration options for the underlying Doctrine doc-block parser aliases and namespaces are not part of this function and need to be set separately.

Being static this means setting them back is the callers responsibility and there is also the fact that some Doctrine configuration currently can not be reverted easily.

Therefore, having a single side effect free way of using swagger-php seemed like a good idea...

The \\OpenApi\\Generator class

The Generator class can be used in object-oriented (and fluent) style which allows for easy customization if needed.

In that case to actually process the given input files the non-static method generate() is to be used.

Full example of using the Generator class to generate OpenApi specs.

require("vendor/autoload.php");
+
+$validate = true;
+$logger = new \\Psr\\Log\\NullLogger();
+$processors = [/* my processors */];
+$finder = \\Symfony\\Component\\Finder\\Finder::create()->files()->name('*.php')->in(__DIR__);
+
+$openapi = (new \\OpenApi\\Generator($logger))
+            ->setProcessors($processors)
+            ->setAliases(['MY' => 'My\\Annotations'])
+            ->setNamespaces(['My\\\\Annotations\\\\'])
+            ->setAnalyser(new \\OpenApi\\Analysers\\TokenAnalyser())
+            ->setVersion(\\OpenApi\\Annotations\\OpenApi::VERSION_3_0_0)
+            ->generate(['/path1/to/project', $finder], new \\OpenApi\\Analysis(), $validate);
+

Aliases and namespaces are additional options that allow to customize the parsing of docblocks.

Defaults:

  • aliases: ['oa' => 'OpenApi\\\\Annotations']

    Aliases help the underlying doctrine annotations library to parse annotations. Effectively they avoid having to write use OpenApi\\Annotations as OA; in your code and make @OA\\property(..) annotations still work.

  • namespaces: ['OpenApi\\\\Annotations\\\\']

    Namespaces control which annotation namespaces can be autoloaded automatically. Under the hood this is handled by registering a custom loader with the doctrine annotation library.

Advantages:

  • The Generator code will handle configuring things as before in a single place
  • Static settings will be reverted to the default once finished
  • The get/set methods allow for using type hints
  • Static configuration is deprecated and can be removed at some point without code changes
  • Build in support for PSR logger
  • Support for Symfony Finder, \\SplInfo and file/directory names (\`string) as source.

The minimum code required, using the generate() method, looks quite similar to the old scan() code:

    /**
+     * Generate OpenAPI spec by scanning the given source files.
+     *
+     * @param iterable      $sources  PHP source files to scan.
+     *                                Supported sources:
+     *                                * string - file / directory name
+     *                                * \\SplFileInfo
+     *                                * \\Symfony\\Component\\Finder\\Finder
+     * @param null|Analysis $analysis custom analysis instance
+     * @param bool          $validate flag to enable/disable validation of the returned spec
+     */
+    public function generate(iterable $sources, ?Analysis $analysis = null, bool $validate = true): \\OpenApi\\OpenApi { /* ... */ }
+
require("vendor/autoload.php");
+
+$openapi = (new \\OpenApi\\Generator())->generate(['/path1/to/project']);
+

For those that want to type even less and keep using a plain array to configure swagger-php there is also a static version:

<?php
+require("vendor/autoload.php");
+
+$openapi = \\OpenApi\\Generator::scan(['/path/to/project']);
+
+header('Content-Type: application/x-yaml');
+echo $openapi->toYaml();
+

Note: While using the same name as the old scan() function, the Generator::scan method is not 100% backwards compatible.

    /**
+     * Static  wrapper around \`Generator::generate()\`.
+     *
+     * @param iterable $sources PHP source files to scan.
+     *                          Supported sources:
+     *                          * string
+     *                          * \\SplFileInfo
+     *                          * \\Symfony\\Component\\Finder\\Finder
+     * @param array    $options
+     *                          aliases:    null|array                    Defaults to \`['oa' => 'OpenApi\\\\Annotations']\`.
+     *                          namespaces: null|array                    Defaults to \`['OpenApi\\\\Annotations\\\\']\`.
+     *                          analyser:   null|AnalyserInterface        Defaults to a new \`ReflectionAnalyser\` supporting both docblocks and attributes.
+     *                          analysis:   null|Analysis                 Defaults to a new \`Analysis\`.
+     *                          processors: null|array                    Defaults to \`Analysis::processors()\`.
+     *                          logger:     null|\\Psr\\Log\\LoggerInterface If not set logging will use \\OpenApi\\Logger as before.
+     *                          validate:   bool                          Defaults to \`true\`.
+     */
+    public static function scan(iterable $sources, array $options = []): OpenApi { /* ... */ }
+

Most notably the exclude and pattern keys are no longer supported. Instead, a Symfony Finder instance can be passed in as source directly (same as with Generator::generate()).

If needed, the \\OpenApi\\Util class provides a builder method that allows to keep the status-quo

$exclude = ['tests'];
+$pattern = '*.php';
+
+$openapi = \\OpenApi\\Generator::scan(\\OpenApi\\Util::finder(__DIR__, $exclude, $pattern));
+
+// same as
+
+$openapi = \\OpenApi\\scan(__DIR__, ['exclude' => $exclude, 'pattern' => $pattern]);
+
`,31),o=[p];function c(l,i,u,r,k,d){return a(),s("div",null,o)}var f=n(e,[["render",c]]);export{h as __pageData,f as default}; diff --git a/assets/reference_generator.md.681f1e2d.lean.js b/assets/reference_generator.md.681f1e2d.lean.js new file mode 100644 index 000000000..3cf922def --- /dev/null +++ b/assets/reference_generator.md.681f1e2d.lean.js @@ -0,0 +1 @@ +import{_ as n,c as s,o as a,a as t}from"./app.d3800f98.js";const h='{"title":"Using the Generator","description":"","frontmatter":{},"headers":[{"level":2,"title":"Introduction","slug":"introduction"},{"level":2,"title":"The \\\\OpenApi\\\\scan() function","slug":"the-openapi-scan-function"},{"level":2,"title":"The \\\\OpenApi\\\\Generator class","slug":"the-openapi-generator-class"}],"relativePath":"reference/generator.md"}',e={},p=t("",31),o=[p];function c(l,i,u,r,k,d){return a(),s("div",null,o)}var f=n(e,[["render",c]]);export{h as __pageData,f as default}; diff --git a/assets/reference_index.md.c170f535.js b/assets/reference_index.md.c170f535.js new file mode 100644 index 000000000..7e823f837 --- /dev/null +++ b/assets/reference_index.md.c170f535.js @@ -0,0 +1 @@ +import{_ as e,c as t,o,a as r}from"./app.d3800f98.js";const f='{"title":"Reference","description":"","frontmatter":{},"headers":[],"relativePath":"reference/index.md"}',a={},n=r('

Reference

In total there are a number of different aspects to using swagger-php. Depending on how custom your requirements are this might be limited to just annotating your code and using the command line tool.

However, swagger-php offers more.

  • Attributes

    The new way of adding meta-data to your codebase. Requires PHP 8.1

  • Docblock annotations

    The 'traditional' way of documenting your API.

  • The Generator

    The \\OpenAPI\\Generator class is the main entry point to programmatically generate OpenAPI documents from your code.

  • Processors

    swagger-php comes with a list of pre-defined processors that convert the raw data to a complete OpenAPI document. Custom processors can be added or existing removed to tweak swagger-php` to your requirements.

',4),s=[n];function c(i,d,p,h,l,m){return o(),t("div",null,s)}var _=e(a,[["render",c]]);export{f as __pageData,_ as default}; diff --git a/assets/reference_index.md.c170f535.lean.js b/assets/reference_index.md.c170f535.lean.js new file mode 100644 index 000000000..9e17ac4e5 --- /dev/null +++ b/assets/reference_index.md.c170f535.lean.js @@ -0,0 +1 @@ +import{_ as e,c as t,o,a as r}from"./app.d3800f98.js";const f='{"title":"Reference","description":"","frontmatter":{},"headers":[],"relativePath":"reference/index.md"}',a={},n=r("",4),s=[n];function c(i,d,p,h,l,m){return o(),t("div",null,s)}var _=e(a,[["render",c]]);export{f as __pageData,_ as default}; diff --git a/assets/reference_processors.md.6f2ce137.js b/assets/reference_processors.md.6f2ce137.js new file mode 100644 index 000000000..ce7c15ffd --- /dev/null +++ b/assets/reference_processors.md.6f2ce137.js @@ -0,0 +1 @@ +import{_ as e,c as t,o as r,a}from"./app.d3800f98.js";const u='{"title":"Processors","description":"","frontmatter":{},"headers":[{"level":2,"title":"DocBlockDescriptions","slug":"docblockdescriptions"},{"level":2,"title":"MergeIntoOpenApi","slug":"mergeintoopenapi"},{"level":2,"title":"MergeIntoComponents","slug":"mergeintocomponents"},{"level":2,"title":"ExpandClasses","slug":"expandclasses"},{"level":2,"title":"ExpandInterfaces","slug":"expandinterfaces"},{"level":2,"title":"ExpandTraits","slug":"expandtraits"},{"level":2,"title":"ExpandEnums","slug":"expandenums"},{"level":2,"title":"AugmentSchemas","slug":"augmentschemas"},{"level":2,"title":"AugmentRequestBody","slug":"augmentrequestbody"},{"level":2,"title":"AugmentProperties","slug":"augmentproperties"},{"level":2,"title":"BuildPaths","slug":"buildpaths"},{"level":2,"title":"AugmentParameters","slug":"augmentparameters"},{"level":3,"title":"Config settings","slug":"config-settings"},{"level":2,"title":"AugmentRefs","slug":"augmentrefs"},{"level":2,"title":"MergeJsonContent","slug":"mergejsoncontent"},{"level":2,"title":"MergeXmlContent","slug":"mergexmlcontent"},{"level":2,"title":"OperationId","slug":"operationid"},{"level":3,"title":"Config settings","slug":"config-settings-1"},{"level":2,"title":"CleanUnmerged","slug":"cleanunmerged"},{"level":2,"title":"CleanUnusedComponents","slug":"cleanunusedcomponents"}],"relativePath":"reference/processors.md"}',n={},s=a('

Processors

This page is generated automatically from the swagger-php sources.

For improvements head over to GitHub and create a PR \u{1F609}

DocBlockDescriptions

Checks if the annotation has a summary and/or description property and uses the text in the comment block (above the annotations) as summary and/or description.

Use null, for example: @Annotation(description=null), if you don't want the annotation to have a description.

MergeIntoOpenApi

Merge all @OA\\OpenApi annotations into one.

MergeIntoComponents

Merge reusable annotation into @OA\\Schemas.

ExpandClasses

Iterate over the chain of ancestors of a schema and:

  • if the ancestor has a schema => inherit from the ancestor if it has a schema (allOf) and stop.
  • else => merge ancestor properties into the schema.

ExpandInterfaces

Look at all (direct) interfaces for a schema and:

  • merge interfaces annotations/methods into the schema if the interface does not have a schema itself
  • inherit from the interface if it has a schema (allOf).

ExpandTraits

Look at all (direct) traits for a schema and:

  • merge trait annotations/methods/properties into the schema if the trait does not have a schema itself
  • inherit from the trait if it has a schema (allOf).

ExpandEnums

Expands PHP enums.

Determines schema, enum and type.

AugmentSchemas

Use the Schema context to extract useful information and inject that into the annotation.

Merges properties.

AugmentRequestBody

Use the RequestBody context to extract useful information and inject that into the annotation.

AugmentProperties

Use the property context to extract useful information and inject that into the annotation.

BuildPaths

Build the openapi->paths using the detected @OA\\PathItem and @OA\\Operation (@OA\\Get, @OA\\Post, etc).

AugmentParameters

Config settings

augmentParameters.augmentOperationParameters : bool

No details available.

AugmentRefs

MergeJsonContent

Split JsonContent into Schema and MediaType.

MergeXmlContent

Split XmlContent into Schema and MediaType.

OperationId

Generate the OperationId based on the context of the OpenApi annotation.

Config settings

operationId.hash : bool

No details available.

CleanUnmerged

CleanUnusedComponents

',45),o=[s];function i(h,p,c,d,l,g){return r(),t("div",null,o)}var f=e(n,[["render",i]]);export{u as __pageData,f as default}; diff --git a/assets/reference_processors.md.6f2ce137.lean.js b/assets/reference_processors.md.6f2ce137.lean.js new file mode 100644 index 000000000..b17865cd7 --- /dev/null +++ b/assets/reference_processors.md.6f2ce137.lean.js @@ -0,0 +1 @@ +import{_ as e,c as t,o as r,a}from"./app.d3800f98.js";const u='{"title":"Processors","description":"","frontmatter":{},"headers":[{"level":2,"title":"DocBlockDescriptions","slug":"docblockdescriptions"},{"level":2,"title":"MergeIntoOpenApi","slug":"mergeintoopenapi"},{"level":2,"title":"MergeIntoComponents","slug":"mergeintocomponents"},{"level":2,"title":"ExpandClasses","slug":"expandclasses"},{"level":2,"title":"ExpandInterfaces","slug":"expandinterfaces"},{"level":2,"title":"ExpandTraits","slug":"expandtraits"},{"level":2,"title":"ExpandEnums","slug":"expandenums"},{"level":2,"title":"AugmentSchemas","slug":"augmentschemas"},{"level":2,"title":"AugmentRequestBody","slug":"augmentrequestbody"},{"level":2,"title":"AugmentProperties","slug":"augmentproperties"},{"level":2,"title":"BuildPaths","slug":"buildpaths"},{"level":2,"title":"AugmentParameters","slug":"augmentparameters"},{"level":3,"title":"Config settings","slug":"config-settings"},{"level":2,"title":"AugmentRefs","slug":"augmentrefs"},{"level":2,"title":"MergeJsonContent","slug":"mergejsoncontent"},{"level":2,"title":"MergeXmlContent","slug":"mergexmlcontent"},{"level":2,"title":"OperationId","slug":"operationid"},{"level":3,"title":"Config settings","slug":"config-settings-1"},{"level":2,"title":"CleanUnmerged","slug":"cleanunmerged"},{"level":2,"title":"CleanUnusedComponents","slug":"cleanunusedcomponents"}],"relativePath":"reference/processors.md"}',n={},s=a("",45),o=[s];function i(h,p,c,d,l,g){return r(),t("div",null,o)}var f=e(n,[["render",i]]);export{u as __pageData,f as default}; diff --git a/assets/related-projects.md.2420d622.js b/assets/related-projects.md.2420d622.js new file mode 100644 index 000000000..8922531f1 --- /dev/null +++ b/assets/related-projects.md.2420d622.js @@ -0,0 +1 @@ +import{_ as e,c as t,o as r,a}from"./app.d3800f98.js";const u='{"title":"Related projects","description":"","frontmatter":{"sidebar":false},"headers":[],"relativePath":"related-projects.md"}',n={},o=a('

Related projects

ProjectDescription
Swagger UIThe webinterface for reading the generated documentation
Swagger ExplainedBrowse the spec by using an swagger.json.
silex2swaggerGenerate swagger documentation from Silex Annotations
yii2-swaggerswagger-php integration with yii2
Lumen swaggerswagger-php integration with lumen/laravel
NelmioApiDocBundleSymfony bundle on top of swagger-php
auto-swagger-uiAutomatically add swagger ui and json to your application
openapi-routerConfigure framework routes from OpenApi annotations
openapi-verifierVerify response against OpenAPI specification in PHPUnit
openapi-filterFilter internal paths, operations, parameters, etc
OpenAPI-Symfony-RoutingLoad routes in Symfony based on OpenAPI annotations
Swag It PHPConvert JSON to PHP Swagger annotations
Laravel SwaggerOpenApi or Swagger integration to Laravel
openapi-extrasExtra annotations for swagger-php
openapi-serializeSerialize an object using swagger-php

Is a related project missing? Create a pull request!

',3),i=[o];function d(p,s,g,l,h,f){return r(),t("div",null,i)}var _=e(n,[["render",d]]);export{u as __pageData,_ as default}; diff --git a/assets/related-projects.md.2420d622.lean.js b/assets/related-projects.md.2420d622.lean.js new file mode 100644 index 000000000..f9285a666 --- /dev/null +++ b/assets/related-projects.md.2420d622.lean.js @@ -0,0 +1 @@ +import{_ as e,c as t,o as r,a}from"./app.d3800f98.js";const u='{"title":"Related projects","description":"","frontmatter":{"sidebar":false},"headers":[],"relativePath":"related-projects.md"}',n={},o=a("",3),i=[o];function d(p,s,g,l,h,f){return r(),t("div",null,i)}var _=e(n,[["render",d]]);export{u as __pageData,_ as default}; diff --git a/assets/style.29d805fc.css b/assets/style.29d805fc.css new file mode 100644 index 000000000..4f0f50a59 --- /dev/null +++ b/assets/style.29d805fc.css @@ -0,0 +1 @@ +:root{--c-white: #ffffff;--c-white-dark: #f8f8f8;--c-black: #000000;--c-divider-light: rgba(60, 60, 67, .12);--c-divider-dark: rgba(84, 84, 88, .48);--c-text-light-1: #2c3e50;--c-text-light-2: #476582;--c-text-light-3: #90a4b7;--c-brand: #3eaf7c;--c-brand-light: #4abf8a;--font-family-base: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif;--font-family-mono: source-code-pro, Menlo, Monaco, Consolas, "Courier New", monospace;--z-index-navbar: 10;--z-index-sidebar: 6;--shadow-1: 0 1px 2px rgba(0, 0, 0, .04), 0 1px 2px rgba(0, 0, 0, .06);--shadow-2: 0 3px 12px rgba(0, 0, 0, .07), 0 1px 4px rgba(0, 0, 0, .07);--shadow-3: 0 12px 32px rgba(0, 0, 0, .1), 0 2px 6px rgba(0, 0, 0, .08);--shadow-4: 0 14px 44px rgba(0, 0, 0, .12), 0 3px 9px rgba(0, 0, 0, .12);--shadow-5: 0 18px 56px rgba(0, 0, 0, .16), 0 4px 12px rgba(0, 0, 0, .16);--header-height: 3.6rem}:root{--c-divider: var(--c-divider-light);--c-text: var(--c-text-light-1);--c-text-light: var(--c-text-light-2);--c-text-lighter: var(--c-text-light-3);--c-bg: var(--c-white);--c-bg-accent: var(--c-white-dark);--code-line-height: 24px;--code-font-family: var(--font-family-mono);--code-font-size: 14px;--code-inline-bg-color: rgba(27, 31, 35, .05);--code-bg-color: #282c34}*,:before,:after{box-sizing:border-box}html{line-height:1.4;font-size:16px;-webkit-text-size-adjust:100%}body{margin:0;width:100%;min-width:320px;min-height:100vh;line-height:1.4;font-family:var(--font-family-base);font-size:16px;font-weight:400;color:var(--c-text);background-color:var(--c-bg);direction:ltr;font-synthesis:none;text-rendering:optimizeLegibility;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}main{display:block}h1,h2,h3,h4,h5,h6{margin:0;line-height:1.25}h1,h2,h3,h4,h5,h6,strong,b{font-weight:600}h1:hover .header-anchor,h1:focus .header-anchor,h2:hover .header-anchor,h2:focus .header-anchor,h3:hover .header-anchor,h3:focus .header-anchor,h4:hover .header-anchor,h4:focus .header-anchor,h5:hover .header-anchor,h5:focus .header-anchor,h6:hover .header-anchor,h6:focus .header-anchor{opacity:1}h1{margin-top:1.5rem;font-size:1.9rem}@media screen and (min-width: 420px){h1{font-size:2.2rem}}h2{margin-top:2.25rem;margin-bottom:1.25rem;border-bottom:1px solid var(--c-divider);padding-bottom:.3rem;line-height:1.25;font-size:1.65rem}h2+h3{margin-top:1.5rem}h3{margin-top:2rem;font-size:1.35rem}h4{font-size:1.15rem}p,ol,ul{margin:1rem 0;line-height:1.7}a,area,button,[role=button],input,label,select,summary,textarea{touch-action:manipulation}a{text-decoration:none;color:var(--c-brand)}a:hover{text-decoration:underline}a.header-anchor{float:left;margin-top:.125em;margin-left:-.87em;padding-right:.23em;font-size:.85em;opacity:0}a.header-anchor:hover,a.header-anchor:focus{text-decoration:none}figure{margin:0}img{max-width:100%}ul,ol{padding-left:1.25em}li>ul,li>ol{margin:0}table{display:block;border-collapse:collapse;margin:1rem 0;overflow-x:auto}tr{border-top:1px solid #dfe2e5}tr:nth-child(2n){background-color:#f6f8fa}th,td{border:1px solid #dfe2e5;padding:.6em 1em}blockquote{margin:1rem 0;border-left:.2rem solid #dfe2e5;padding:.25rem 0 .25rem 1rem;font-size:1rem;color:#999}blockquote>p{margin:0}form{margin:0}.theme.sidebar-open .sidebar-mask{display:block}.theme.no-navbar>h1,.theme.no-navbar>h2,.theme.no-navbar>h3,.theme.no-navbar>h4,.theme.no-navbar>h5,.theme.no-navbar>h6{margin-top:1.5rem;padding-top:0}.theme.no-navbar aside{top:0}@media screen and (min-width: 720px){.theme.no-sidebar aside{display:none}.theme.no-sidebar main{margin-left:0}}.sidebar-mask{position:fixed;z-index:2;display:none;width:100vw;height:100vh}code{margin:0;border-radius:3px;padding:.25rem .5rem;font-family:var(--code-font-family);font-size:.85em;color:var(--c-text-light);background-color:var(--code-inline-bg-color)}code .token.deleted{color:#ec5975}code .token.inserted{color:var(--c-brand)}div[class*=language-]{position:relative;margin:1rem -1.5rem;background-color:var(--code-bg-color);overflow-x:auto}li>div[class*=language-]{border-radius:6px 0 0 6px;margin:1rem -1.5rem 1rem -1.25rem;line-height:initial}@media (min-width: 420px){div[class*=language-]{margin:1rem 0;border-radius:6px}li>div[class*=language-]{margin:1rem 0 1rem 0rem;border-radius:6px}}[class*=language-] pre,[class*=language-] code{text-align:left;white-space:pre;word-spacing:normal;word-break:normal;word-wrap:normal;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none;background:transparent}[class*=language-] pre{position:relative;z-index:1;margin:0;padding:1.25rem 1.5rem;overflow-x:auto}[class*=language-] code{padding:0;line-height:var(--code-line-height);font-size:var(--code-font-size);color:#eee}.highlight-lines{position:absolute;top:0;bottom:0;left:0;padding:1.25rem 0;width:100%;line-height:var(--code-line-height);font-family:var(--code-font-family);font-size:var(--code-font-size);user-select:none;overflow:hidden}.highlight-lines .highlighted{background-color:#000000a8}div[class*=language-].line-numbers-mode{padding-left:3.5rem}.line-numbers-wrapper{position:absolute;top:0;bottom:0;left:0;z-index:3;border-right:1px solid rgba(0,0,0,.5);padding:1.25rem 0;width:3.5rem;text-align:center;line-height:var(--code-line-height);font-family:var(--code-font-family);font-size:var(--code-font-size);color:#888}div[class*=language-]:before{position:absolute;top:.6em;right:1em;z-index:2;font-size:.8rem;color:#888}div[class~=language-html]:before,div[class~=language-markup]:before{content:"html"}div[class~=language-md]:before,div[class~=language-markdown]:before{content:"md"}div[class~=language-css]:before{content:"css"}div[class~=language-sass]:before{content:"sass"}div[class~=language-scss]:before{content:"scss"}div[class~=language-less]:before{content:"less"}div[class~=language-stylus]:before{content:"styl"}div[class~=language-js]:before,div[class~=language-javascript]:before{content:"js"}div[class~=language-ts]:before,div[class~=language-typescript]:before{content:"ts"}div[class~=language-json]:before{content:"json"}div[class~=language-rb]:before,div[class~=language-ruby]:before{content:"rb"}div[class~=language-py]:before,div[class~=language-python]:before{content:"py"}div[class~=language-sh]:before,div[class~=language-bash]:before{content:"sh"}div[class~=language-php]:before{content:"php"}div[class~=language-go]:before{content:"go"}div[class~=language-rust]:before{content:"rust"}div[class~=language-java]:before{content:"java"}div[class~=language-c]:before{content:"c"}div[class~=language-yaml]:before{content:"yaml"}div[class~=language-dockerfile]:before{content:"dockerfile"}div[class~=language-vue]:before{content:"vue"}.token.comment,.token.block-comment,.token.prolog,.token.doctype,.token.cdata{color:#999}.token.punctuation{color:#ccc}.token.tag,.token.attr-name,.token.namespace,.token.deleted{color:#e2777a}.token.function-name{color:#6196cc}.token.boolean,.token.number,.token.function{color:#f08d49}.token.property,.token.class-name,.token.constant,.token.symbol{color:#f8c555}.token.selector,.token.important,.token.atrule,.token.keyword,.token.builtin{color:#cc99cd}.token.string,.token.char,.token.attr-value,.token.regex,.token.variable{color:#7ec699}.token.operator,.token.entity,.token.url{color:#67cdcc}.token.important,.token.bold{font-weight:700}.token.italic{font-style:italic}.token.entity{cursor:help}.token.inserted{color:green}.custom-block.tip,.custom-block.info,.custom-block.warning,.custom-block.danger{margin:1rem 0;border-left:.5rem solid;padding:.1rem 1.5rem;overflow-x:auto}.custom-block.tip{background-color:#f3f5f7;border-color:var(--c-brand)}.custom-block.info{background-color:#f3f5f7;border-color:var(--c-text-light-2)}.custom-block.warning{border-color:#e7c000;color:#6b5900;background-color:#ffe5644d}.custom-block.warning .custom-block-title{color:#b29400}.custom-block.warning a{color:var(--c-text)}.custom-block.danger{border-color:#c00;color:#4d0000;background-color:#ffe6e6}.custom-block.danger .custom-block-title{color:#900}.custom-block.danger a{color:var(--c-text)}.custom-block.details{position:relative;display:block;border-radius:2px;margin:1.6em 0;padding:1.6em;background-color:#eee}.custom-block.details h4{margin-top:0}.custom-block.details figure:last-child,.custom-block.details p:last-child{margin-bottom:0;padding-bottom:0}.custom-block.details summary{outline:none;cursor:pointer}.custom-block-title{margin-bottom:-.4rem;font-weight:600}.sidebar-links{margin:0;padding:0;list-style:none}.sidebar-link-item{display:block;margin:0;border-left:.25rem solid transparent;color:var(--c-text)}a.sidebar-link-item:hover{text-decoration:none;color:var(--c-brand)}a.sidebar-link-item.active{color:var(--c-brand)}.sidebar>.sidebar-links{padding:.75rem 0 5rem}@media (min-width: 720px){.sidebar>.sidebar-links{padding:1.5rem 0}}.sidebar>.sidebar-links>.sidebar-link+.sidebar-link{padding-top:.5rem}@media (min-width: 720px){.sidebar>.sidebar-links>.sidebar-link+.sidebar-link{padding-top:1.25rem}}.sidebar>.sidebar-links>.sidebar-link>.sidebar-link-item{padding:.35rem 1.5rem .35rem 1.25rem;font-size:1.1rem;font-weight:700}.sidebar>.sidebar-links>.sidebar-link>a.sidebar-link-item.active{border-left-color:var(--c-brand);font-weight:600}.sidebar>.sidebar-links>.sidebar-link>.sidebar-links>.sidebar-link>.sidebar-link-item{display:block;padding:.35rem 1.5rem .35rem 2rem;line-height:1.4;font-size:1rem;font-weight:400}.sidebar>.sidebar-links>.sidebar-link>.sidebar-links>.sidebar-link>a.sidebar-link-item.active{border-left-color:var(--c-brand);font-weight:600}.sidebar>.sidebar-links>.sidebar-link>.sidebar-links>.sidebar-link>.sidebar-links>.sidebar-link>.sidebar-link-item{display:block;padding:.3rem 1.5rem .3rem 3rem;line-height:1.4;font-size:.9rem;font-weight:400}.sidebar>.sidebar-links>.sidebar-link>.sidebar-links>.sidebar-link>.sidebar-links>.sidebar-link>.sidebar-links>.sidebar-link>.sidebar-link-item{display:block;padding:.3rem 1.5rem .3rem 4rem;line-height:1.4;font-size:.9rem;font-weight:400}.debug[data-v-765646fb]{box-sizing:border-box;position:fixed;right:8px;bottom:8px;z-index:9999;border-radius:4px;width:74px;height:32px;color:#eee;overflow:hidden;cursor:pointer;background-color:#000000d9;transition:all .15s ease}.debug[data-v-765646fb]:hover{background-color:#000000bf}.debug.open[data-v-765646fb]{right:0;bottom:0;width:100%;height:100%;margin-top:0;border-radius:0;padding:0;overflow:scroll}@media (min-width: 512px){.debug.open[data-v-765646fb]{width:512px}}.debug.open[data-v-765646fb]:hover{background-color:#000000d9}.title[data-v-765646fb]{margin:0;padding:6px 16px;line-height:20px;font-size:13px}.block[data-v-765646fb]{margin:2px 0 0;border-top:1px solid rgba(255,255,255,.16);padding:8px 16px;font-family:Hack,monospace;font-size:13px}.block+.block[data-v-765646fb]{margin-top:8px}.icon.outbound{position:relative;top:-1px;display:inline-block;vertical-align:middle;color:var(--c-text-lighter)}.item[data-v-49fe041d]{display:block;padding:0 1.5rem;line-height:36px;font-size:1rem;font-weight:600;color:var(--c-text);white-space:nowrap}.item[data-v-49fe041d]:hover,.item.active[data-v-49fe041d]{text-decoration:none;color:var(--c-brand)}.item.external[data-v-49fe041d]:hover{border-bottom-color:transparent;color:var(--c-text)}@media (min-width: 720px){.item[data-v-49fe041d]{border-bottom:2px solid transparent;padding:0;line-height:24px;font-size:.9rem;font-weight:500}.item[data-v-49fe041d]:hover,.item.active[data-v-49fe041d]{border-bottom-color:var(--c-brand);color:var(--c-text)}}.home-hero[data-v-5d8b683d]{margin:2.5rem 0 2.75rem;padding:0 1.5rem;text-align:center}@media (min-width: 420px){.home-hero[data-v-5d8b683d]{margin:3.5rem 0}}@media (min-width: 720px){.home-hero[data-v-5d8b683d]{margin:4rem 0 4.25rem}}.figure[data-v-5d8b683d]{padding:0 1.5rem}.image[data-v-5d8b683d]{display:block;margin:0 auto;width:auto;max-width:100%;max-height:280px}.title[data-v-5d8b683d]{margin-top:1.5rem;font-size:2rem}@media (min-width: 420px){.title[data-v-5d8b683d]{font-size:3rem}}@media (min-width: 720px){.title[data-v-5d8b683d]{margin-top:2rem}}.tagline[data-v-5d8b683d]{margin:0;margin-top:.25rem;line-height:1.3;font-size:1.2rem;color:var(--c-text-light)}@media (min-width: 420px){.tagline[data-v-5d8b683d]{line-height:1.2;font-size:1.6rem}}.action[data-v-5d8b683d]{margin-top:1.5rem;display:inline-block}.action.alt[data-v-5d8b683d]{margin-left:1.5rem}@media (min-width: 420px){.action[data-v-5d8b683d]{margin-top:2rem;display:inline-block}}.action[data-v-5d8b683d] .item{display:inline-block;border-radius:6px;padding:0 20px;line-height:44px;font-size:1rem;font-weight:500;color:var(--c-bg);background-color:var(--c-brand);border:2px solid var(--c-brand);transition:background-color .1s ease}.action.alt[data-v-5d8b683d] .item{background-color:var(--c-bg);color:var(--c-brand)}.action[data-v-5d8b683d] .item:hover{text-decoration:none;color:var(--c-bg);background-color:var(--c-brand-light)}@media (min-width: 420px){.action[data-v-5d8b683d] .item{padding:0 24px;line-height:52px;font-size:1.2rem;font-weight:500}}.home-features[data-v-245bde66]{margin:0 auto;padding:2.5rem 0 2.75rem;max-width:960px}.home-hero+.home-features[data-v-245bde66]{padding-top:0}@media (min-width: 420px){.home-features[data-v-245bde66]{padding:3.25rem 0 3.5rem}.home-hero+.home-features[data-v-245bde66]{padding-top:0}}@media (min-width: 720px){.home-features[data-v-245bde66]{padding-right:1.5rem;padding-left:1.5rem}}.wrapper[data-v-245bde66]{padding:0 1.5rem}.home-hero+.home-features .wrapper[data-v-245bde66]{border-top:1px solid var(--c-divider);padding-top:2.5rem}@media (min-width: 420px){.home-hero+.home-features .wrapper[data-v-245bde66]{padding-top:3.25rem}}@media (min-width: 720px){.wrapper[data-v-245bde66]{padding-right:0;padding-left:0}}.container[data-v-245bde66]{margin:0 auto;max-width:392px}@media (min-width: 720px){.container[data-v-245bde66]{max-width:960px}}.features[data-v-245bde66]{display:flex;flex-wrap:wrap;margin:-20px -24px}.feature[data-v-245bde66]{flex-shrink:0;padding:20px 24px;width:100%}@media (min-width: 720px){.feature[data-v-245bde66]{width:calc(100% / 3)}}.title[data-v-245bde66]{margin:0;border-bottom:0;line-height:1.4;font-size:1.25rem;font-weight:500}@media (min-width: 420px){.title[data-v-245bde66]{font-size:1.4rem}}.details[data-v-245bde66]{margin:0;line-height:1.6;font-size:1rem;color:var(--c-text-light)}.title+.details[data-v-245bde66]{padding-top:.25rem}.footer[data-v-bff49316]{margin:0 auto;max-width:960px}@media (min-width: 720px){.footer[data-v-bff49316]{padding:0 1.5rem}}.container[data-v-bff49316]{padding:2rem 1.5rem 2.25rem}.home-hero+.footer .container[data-v-bff49316],.home-features+.footer .container[data-v-bff49316],.home-content+.footer .container[data-v-bff49316]{border-top:1px solid var(--c-divider)}@media (min-width: 420px){.container[data-v-bff49316]{padding:3rem 1.5rem 3.25rem}}.text[data-v-bff49316]{margin:0;text-align:center;line-height:1.4;font-size:.9rem;color:var(--c-text-light)}.home[data-v-8382b818]{padding-top:var(--header-height)}.home-content[data-v-8382b818]{max-width:960px;margin:0 auto;padding:0 1.5rem}.nav-bar-title[data-v-016a8bd8]{font-size:1.3rem;font-weight:600;color:var(--c-text);display:flex;justify-content:center;align-items:center}.nav-bar-title[data-v-016a8bd8]:hover{text-decoration:none}.logo[data-v-016a8bd8]{margin-right:.75rem;height:1.3rem;vertical-align:bottom}.item[data-v-07381bdb]{display:block;padding:0 1.5rem 0 2.5rem;line-height:32px;font-size:.9rem;font-weight:500;color:var(--c-text);white-space:nowrap}@media (min-width: 720px){.item[data-v-07381bdb]{padding:0 24px 0 12px;line-height:32px;font-size:.85rem;font-weight:500;color:var(--c-text);white-space:nowrap}.item.active .arrow[data-v-07381bdb]{opacity:1}}.item[data-v-07381bdb]:hover,.item.active[data-v-07381bdb]{text-decoration:none;color:var(--c-brand)}.item.external[data-v-07381bdb]:hover{border-bottom-color:transparent;color:var(--c-text)}@media (min-width: 720px){.arrow[data-v-07381bdb]{display:inline-block;margin-right:8px;border-top:6px solid #ccc;border-right:4px solid transparent;border-bottom:0;border-left:4px solid transparent;vertical-align:middle;opacity:0;transform:translateY(-2px) rotate(-90deg)}}.nav-dropdown-link[data-v-18d75f62]{position:relative;height:36px;overflow:hidden;cursor:pointer}@media (min-width: 720px){.nav-dropdown-link[data-v-18d75f62]{height:auto;overflow:visible}.nav-dropdown-link:hover .dialog[data-v-18d75f62]{display:block}}.nav-dropdown-link.open[data-v-18d75f62]{height:auto}.button[data-v-18d75f62]{display:block;border:0;padding:0 1.5rem;width:100%;text-align:left;line-height:36px;font-family:var(--font-family-base);font-size:1rem;font-weight:600;color:var(--c-text);white-space:nowrap;background-color:transparent;cursor:pointer}.button[data-v-18d75f62]:focus{outline:0}@media (min-width: 720px){.button[data-v-18d75f62]{border-bottom:2px solid transparent;padding:0;line-height:24px;font-size:.9rem;font-weight:500}}.button-arrow[data-v-18d75f62]{display:inline-block;margin-top:-1px;margin-left:8px;border-top:6px solid #ccc;border-right:4px solid transparent;border-bottom:0;border-left:4px solid transparent;vertical-align:middle}.button-arrow.right[data-v-18d75f62]{transform:rotate(-90deg)}@media (min-width: 720px){.button-arrow.right[data-v-18d75f62]{transform:rotate(0)}}.dialog[data-v-18d75f62]{margin:0;padding:0;list-style:none}@media (min-width: 720px){.dialog[data-v-18d75f62]{display:none;position:absolute;top:26px;right:-8px;border-radius:6px;padding:12px 0;min-width:128px;background-color:var(--c-bg);box-shadow:var(--shadow-3)}}.nav-links[data-v-35b91e7e]{padding:.75rem 0;border-bottom:1px solid var(--c-divider)}@media (min-width: 720px){.nav-links[data-v-35b91e7e]{display:flex;padding:6px 0 0;align-items:center;border-bottom:0}.item+.item[data-v-35b91e7e]{padding-left:24px}}.sidebar-button{position:absolute;top:.6rem;left:1rem;display:none;padding:.6rem;cursor:pointer}.sidebar-button .icon{display:block;width:1.25rem;height:1.25rem}@media screen and (max-width: 719px){.sidebar-button{display:block}}.nav-bar[data-v-40587210]{position:fixed;top:0;right:0;left:0;z-index:var(--z-index-navbar);display:flex;justify-content:space-between;align-items:center;border-bottom:1px solid var(--c-divider);padding:.7rem 1.5rem .7rem 4rem;height:var(--header-height);background-color:var(--c-bg)}@media (min-width: 720px){.nav-bar[data-v-40587210]{padding:.7rem 1.5rem}}.flex-grow[data-v-40587210]{flex-grow:1}.nav[data-v-40587210]{display:none}@media (min-width: 720px){.nav[data-v-40587210]{display:block}}.sidebar[data-v-17c48e2f]{position:fixed;top:var(--header-height);bottom:0;left:0;z-index:var(--z-index-sidebar);border-right:1px solid var(--c-divider);width:16.4rem;background-color:var(--c-bg);overflow-y:auto;transform:translate(-100%);transition:transform .25s ease}@media (min-width: 720px){.sidebar[data-v-17c48e2f]{transform:translate(0)}}@media (min-width: 960px){.sidebar[data-v-17c48e2f]{width:20rem}}.sidebar.open[data-v-17c48e2f]{transform:translate(0)}.nav[data-v-17c48e2f]{display:block}@media (min-width: 720px){.nav[data-v-17c48e2f]{display:none}}.link[data-v-55695e90]{display:inline-block;font-size:1rem;font-weight:500;color:var(--c-text-light)}.link[data-v-55695e90]:hover{text-decoration:none;color:var(--c-brand)}.icon[data-v-55695e90]{margin-left:4px}.last-updated[data-v-7e06cdca]{display:inline-block;margin:0;line-height:1.4;font-size:.9rem;color:var(--c-text-light)}@media (min-width: 960px){.last-updated[data-v-7e06cdca]{font-size:1rem}}.prefix[data-v-7e06cdca]{display:inline-block;font-weight:500}.datetime[data-v-7e06cdca]{display:inline-block;margin-left:6px;font-weight:400}.page-footer[data-v-b65b4b36]{padding-top:1rem;padding-bottom:1rem;overflow:auto}@media (min-width: 960px){.page-footer[data-v-b65b4b36]{display:flex;justify-content:space-between;align-items:center}}.updated[data-v-b65b4b36]{padding-top:4px}@media (min-width: 960px){.updated[data-v-b65b4b36]{padding-top:0}}.next-and-prev-link[data-v-e65a9748]{padding-top:1rem}.container[data-v-e65a9748]{display:flex;justify-content:space-between;border-top:1px solid var(--c-divider);padding-top:1rem}.prev[data-v-e65a9748],.next[data-v-e65a9748]{display:flex;flex-shrink:0;width:50%}.prev[data-v-e65a9748]{justify-content:flex-start;padding-right:12px}.next[data-v-e65a9748]{justify-content:flex-end;padding-left:12px}.link[data-v-e65a9748]{display:inline-flex;align-items:center;max-width:100%;font-size:1rem;font-weight:500}.text[data-v-e65a9748]{display:block;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.icon[data-v-e65a9748]{display:block;flex-shrink:0;width:16px;height:16px;fill:var(--c-text);transform:translateY(1px)}.icon-prev[data-v-e65a9748]{margin-right:8px}.icon-next[data-v-e65a9748]{margin-left:8px}.page[data-v-8fcebc32]{padding-top:var(--header-height)}@media (min-width: 720px){.page[data-v-8fcebc32]{margin-left:16.4rem}}@media (min-width: 960px){.page[data-v-8fcebc32]{margin-left:20rem}}.container[data-v-8fcebc32]{margin:0 auto;padding:0 1.5rem 4rem;max-width:48rem}.content[data-v-8fcebc32]{padding-bottom:1.5rem}@media (max-width: 420px){.content[data-v-8fcebc32]{clear:both}}#ads-container{margin:0 auto}@media (min-width: 420px){#ads-container{position:relative;right:0;float:right;margin:-8px -8px 24px 24px;width:146px}}@media (max-width: 420px){#ads-container{height:105px;margin:1.75rem 0}}@media (min-width: 1400px){#ads-container{position:fixed;right:8px;bottom:8px}}.tabs-component-tabs{border:solid 1px #ddd;border-radius:6px;margin-bottom:5px}@media (min-width: 700px){.tabs-component-tabs{border:0;align-items:stretch;display:flex;justify-content:flex-start;margin-bottom:-1px}}.tabs-component-tab{color:#999;font-size:14px;font-weight:600;margin-right:0;list-style:none}.tabs-component-tab:hover{color:#666}.tabs-component-tab.is-active{color:#000}.tabs-component-tab.is-disabled *{color:#cdcdcd;cursor:not-allowed!important}@media (min-width: 700px){.tabs-component-tab{background-color:#fff;border:solid 1px #ddd;border-radius:3px 3px 0 0;margin-right:.5em;transform:translateY(2px);transition:transform .3s ease}.tabs-component-tab.is-active{border-bottom:solid 1px #fff;z-index:2;transform:translateY(0)}}.tabs-component-tab-a{align-items:center;color:inherit;display:flex;padding:.5em 1.25em;text-decoration:none}.tabs-component-panels{padding:1em 0}@media (min-width: 700px){.tabs-component-panels{background-color:#fff;border:solid 1px #ddd;border-radius:6px;box-shadow:0 0 10px #0000000d;padding:1em;position:relative}}:root{--c-brand: #74a535;--c-brand-light: #94c73d;--c-bg: #fefefe}.tabs-component{margin:2em 0}.tabs-component-panels{padding:0;border:none}.tabs-component-tab-a{padding:.5em}.tabs-component-tab{transform:none}@media (min-width: 700px){.tabs-component-tab.is-active{border-bottom:solid 1px #ddd}} diff --git a/guide/annotations.html b/guide/annotations.html new file mode 100644 index 000000000..ec898a8e1 --- /dev/null +++ b/guide/annotations.html @@ -0,0 +1,96 @@ + + + + + + Annotations | Swagger-PHP + + + + + + + + + +
Swagger-PHP

Annotations

Namespace

Using a namespace alias simplifies typing and improves readability.

All annotations are in the OpenApi\Annotations namespace.

Since Annotations are technically PHP comments, adding use OpenApi\Annotations as OA; is strictly speaking not necessary. However, doctrine will be quite specific about whether an alias is valid or not.

swagger-php will automatically register the @OA alias so all annotations can be used using the @OA shortcut without any additional work.

Doctrine

Annotations are PHP comments (docblocks) containing doctrine style annotations.

INFO

All documentation related to doctrine applies to annotations only.

Example:

<?php
+
+use OpenApi\Annotations as OA;
+
+/**
+ * @OA\Info(title="My First API", version="0.1")
+ */
+class OpenApi {}
+
+class MyController {
+
+    /**
+     * @OA\Get(
+     *     path="/api/resource.json",
+     *     @OA\Response(response="200", description="An example resource")
+     * )
+     */
+    public function resource() {
+        // ...
+    }
+}
+

Escaping

Escaping double quotes

Double quotes can be escaped by doubling them rather than using \

For example:

    @OA\Schema(
+       title="Request",
+       schema="Request",
+       example={
+          "configuration":"{""formConfig"":123}"
+       }
+     )
+

Arrays and Objects

Doctrine annotations support arrays, but use { and } instead of [ and ].

Doctrine also supports objects, which also use { and } and require the property names to be surrounded with ".

DON'T WRITE

/**
+ * @OA\Info(
+ *   title="My first API",
+ *   version="1.0.0",
+ *   contact={
+ *     "email": "support@example.com"
+ *   }
+ * )
+ */
+

This "works" but most objects have an annotation with the same name as the property, such as @OA\Contact for contact:

WRITE

/**
+ * @OA\Info(
+ *   title="My first API",
+ *   version="1.0.0",
+ *   @OA\Contact(
+ *     email="support@example.com"
+ *   )
+ * )
+ */
+

This also adds validation, so when you misspell a property or forget a required property, it will trigger a PHP warning.

For example, if you write emial="support@example.com", swagger-php would generate a notice with Unexpected field "emial" for @OA\Contact(), expecting "name", "email", ...

Placing multiple annotations of the same type will result in an array of objects. For objects, the key is defined by the field with the same name as the annotation: response in a @OA\Response, property in a @OA\Property, etc.

/**
+ * @OA\Get(
+ *   path="/products",
+ *   summary="list products",
+ *   @OA\Response(
+ *     response=200,
+ *     description="A list with products"
+ *   ),
+ *   @OA\Response(
+ *     response="default",
+ *     description="an ""unexpected"" error"
+ *   )
+ * )
+ */
+

Results in

openapi: 3.0.0
+paths:
+  /products:
+    get:
+      summary: "list products"
+      responses:
+        "200":
+          description: "A list with products"
+        default:
+          description: 'an "unexpected" error'
+

Constants

You can use constants inside doctrine annotations.

define("API_HOST", ($env === "production") ? "example.com" : "localhost");
+
/**
+ * @OA\Server(url=API_HOST)
+ */
+

TIP

Using the CLI you might need to include the php file with the constants using the --bootstrap options.

> openapi --bootstrap constants.php
+
+ + + + + \ No newline at end of file diff --git a/guide/attributes.html b/guide/attributes.html new file mode 100644 index 000000000..38dbec53b --- /dev/null +++ b/guide/attributes.html @@ -0,0 +1,33 @@ + + + + + + Attributes | Swagger-PHP + + + + + + + + + +
Swagger-PHP

Attributes

Namespace

Using a namespace alias simplifies typing and improves readability.

All attributes are in the OpenApi\Attributes namespace.

Nesting

Similar to annotations attributes can be top level or nested. However, attributes may be put at the same level if there is no ambiguity. swagger-php will then merge attributes according to the defined rules about parent/child relationships.

Example

Nested:

    #[OA\Get(
+        path: '/api/users',
+        responses: [
+            new OA\Response(response: 200, description: 'AOK'),
+            new OA\Response(response: 401, description: 'Not allowed'),
+        ]
+    )]
+    public function users() { /* ... */ }
+

Not nested:

    #[OA\Get(path: '/api/users')]
+    #[OA\Response(response: 200, description: 'AOK')]
+    #[OA\Response(response: 401, description: 'Not allowed')]
+    public function users() { /* ... */ }
+

Depending on how much nesting there is this can make things a bit simpler and easier to read.

Top level only

Automatic merging of attributes works only at the top level - in the example that would be the method users().

+ + + + + \ No newline at end of file diff --git a/guide/common-techniques.html b/guide/common-techniques.html new file mode 100644 index 000000000..6a5725c21 --- /dev/null +++ b/guide/common-techniques.html @@ -0,0 +1,236 @@ + + + + + + Common techniques | Swagger-PHP + + + + + + + + + +
Swagger-PHP

Common techniques

Annotation placement

You shouldn't place all annotations inside one big block, but scatter them throughout your codebase as close to the relevant source code as appropriate.

swagger-php will scan your project and merge all meta-data into one @OA\OpenApi annotation.

WARNING

As of swagger-php v4 all annotations or attributes must be associated with a structural element (class, method, parameter or enum)

Context awareness

swagger-php looks at the context of the annotation and will augment it with things like property name, data type (doctype and native type hints) as well as a couple other things.

This means in a lot of cases it is not necessary to explicitly document all details.

Example

<?php
+
+/**
+ * @OA\Schema()
+ */
+class Product {
+
+    /**
+     * The product name,
+     * @var string
+     * @OA\Property()
+     */
+    public $name;
+}
+

Results in

openapi: 3.0.0
+components:
+  schemas:
+    Product:
+      properties:
+        name:
+          description: "The product name"
+          type: string
+      type: object
+

As if you'd written

    /**
+     * The product name
+     * @var string
+     *
+     * @OA\Property(
+     *   property="name",
+     *   type="string",
+     *   description="The product name"
+     * )
+     */
+    public $name;
+

Response media type

The @OA\MediaType is used to describe the content:

/**
+ * @OA\Response(
+ *     response=200,
+ *     description="successful operation",
+ *     @OA\MediaType(
+ *         mediaType="application/json",
+ *         @OA\Schema(ref="#/components/schemas/User"),
+ *     )
+ * ),
+ */
+

But because most API requests and responses are JSON, the @OA\JsonContent allows you to simplify this by writing:

/**
+ * @OA\Response(
+ *     response=200,
+ *     description="successful operation",
+ *     @OA\JsonContent(ref="#/components/schemas/User"),
+ * )
+ */
+

During processing the @OA\JsonContent unfolds to @OA\MediaType( mediaType="application/json", @OA\Schema(...) and will generate the same output.

Using references - $ref

It's quite common that endpoints have some overlap in either their request or response data. To keep things DRY (Don't Repeat Yourself) the specification allows reusing components using $ref's

/**
+ * @OA\Schema(
+ *   schema="product_id",
+ *   type="integer",
+ *   format="int64",
+ *   description="The unique identifier of a product in our catalog"
+ * )
+ */
+

Results in:

openapi: 3.0.0
+components:
+  schemas:
+    product_id:
+      description: "The unique identifier of a product in our catalog"
+      type: integer
+      format: int64
+

This doesn't do anything by itself, but now you can reference this fragment by its path in the document tree #/components/schemas/product_id

    /**
+     * @OA\Property(ref="#/components/schemas/product_id")
+     */
+    public $id;
+

Examples

There are more uses cases on how to use refs in the using-refs example.

Array parameters in query

Depending on style-values @OA\Parameter(in="query", name="param", ...) might create urls like this: path?param=123&param=abc which do not work when reading the param values in PHP.

The solution is to change the name param into param[] which will create path?param[]=123&param[]=abc and results in a PHP array.

Vendor extensions

The specification allows for custom properties as long as they start with "x-". Therefore, all swagger-php annotations have an x property which accepts an array (map) and will unfold into "x-" properties.

/**
+ * @OA\Info(
+ *   title="Example",
+ *   version="1.0.0",
+ *   x={
+ *     "some-name": "a-value",
+ *     "another": 2,
+ *     "complex-type": {
+ *       "supported":{
+ *         {"version": "1.0", "level": "baseapi"},
+ *         {"version": "2.1", "level": "fullapi"},
+ *       }
+ *     }
+ *   }
+ * )
+ */
+

Results in:

openapi: 3.0.0
+info:
+  title: Example
+  version: 1
+  x-some-name: a-value
+  x-another: 2
+  x-complex-type:
+    supported:
+      - version: "1.0"
+        level: baseapi
+      - version: "2.1"
+        level: fullapi
+

Enums

PHP 8.1 enums are supported in two main use cases.

Enum cases as value

Enum cases can be used as value in an enum list just like a string, integer or any other primitive type.

Basic enum:

use OpenApi\Attributes as OAT;
+
+enum Suit
+{
+    case Hearts;
+    case Diamonds;
+    case Clubs;
+    case Spades;
+}
+
+class Model
+{
+    #[OAT\Property(enum: [Suit::Hearts, Suit::Diamonds])]
+    protected array $someSuits;
+}
+

Results in:

openapi: 3.0.0
+components:
+  schemas:
+    Model:
+      properties:
+        someSuits:
+          type: array
+          enum:
+            - Hearts
+            - Diamonds
+      type: object
+
+

Backed enums

If the enum is a backed enum, the case backing value is used instead of the name.

Enum schemas

The simples way of using enums is to annotate them as Schema. This allows you to reference them like any other schema in your spec.

use OpenApi\Attributes as OAT;
+
+#[OAT\Schema()]
+enum Colour
+{
+    case GREEN;
+    case BLUE;
+    case RED;
+}
+
+#[OAT\Schema()]
+class Product
+{
+    #[OAT\Property()]
+    public Colour $colour;
+}
+

Results in:

openapi: 3.0.0
+components:
+  schemas:
+    Colour:
+      type: string
+      enum:
+        - GREEN
+        - BLUE
+        - RED
+    Product:
+      properties:
+        colour:
+          $ref: '#/components/schemas/Colour'
+      type: object
+

Backed enums

For backed enums there exist two rules that determine whether the name or backing value is used:

  1. If no schema type is given, the enum name is used.
  2. If a schema type is given, and it matches the backing type, the enum backing value is used.

Using the name of a backed enum:

use OpenApi\Attributes as OAT;
+
+#[OAT\Schema()]
+enum Colour: int
+{
+    case GREEN = 1;
+    case BLUE = 2;
+    case RED = 3;
+}
+
+#[OAT\Schema()]
+class Product
+{
+    #[OAT\Property()]
+    public Colour $colour;
+}
+

Results in:

openapi: 3.0.0
+components:
+  schemas:
+    Colour:
+      type: string
+      enum:
+        - GREEN
+        - BLUE
+        - RED
+    Product:
+      properties:
+        colour:
+          $ref: '#/components/schemas/Colour'
+      type: object
+

Using the backing value:

use OpenApi\Attributes as OAT;
+
+#[OAT\Schema(type: 'integer')]
+enum Colour: int
+{
+    case GREEN = 1;
+    case BLUE = 2;
+    case RED = 3;
+}
+
+#[OAT\Schema()]
+class Product
+{
+    #[OAT\Property()]
+    public Colour $colour;
+}
+

Results in:

openapi: 3.0.0
+components:
+  schemas:
+    Colour:
+      type: integer
+      enum:
+        - 1
+        - 2
+        - 3
+    Product:
+      properties:
+        colour:
+          $ref: '#/components/schemas/Colour'
+      type: object
+
+ + + + + \ No newline at end of file diff --git a/guide/cookbook.html b/guide/cookbook.html new file mode 100644 index 000000000..96006fd4f --- /dev/null +++ b/guide/cookbook.html @@ -0,0 +1,516 @@ + + + + + + Cookbook | Swagger-PHP + + + + + + + + + +
Swagger-PHP

Cookbook

x-tagGroups

OpenApi has the concept of grouping endpoints using tags. On top of that, some tools (redocly, for example) support further grouping via the vendor extension x-tagGroups.

/**
+ * @OA\OpenApi(
+ *   x={
+ *       "tagGroups"=
+ *           {{"name"="User Management", "tags"={"Users", "API keys", "Admin"}}
+ *       }
+ *   }
+ * )
+ */
+

Adding examples to @OA\Response 

/*
+ * @OA\Response(
+ *     response=200,
+ *     description="OK",
+ *     @OA\JsonContent(
+ *         oneOf={
+ *             @OA\Schema(ref="#/components/schemas/Result"),
+ *             @OA\Schema(type="boolean")
+ *         },
+ *         @OA\Examples(example="result", value={"success": true}, summary="An result object."),
+ *         @OA\Examples(example="bool", value=false, summary="A boolean value."),
+ *     )
+ * )
+ */
+

External documentation

OpenApi allows a single reference to external documentation. This is a part of the top level @OA\OpenApi.

/**
+ * @OA\OpenApi(
+ *   @OA\ExternalDocumentation(
+ *     description="More documentation here...",
+ *     url="https://example.com/externaldoc1/"
+ *   )
+ * )
+ */
+

TIP

If no @OA\OpenApi is configured, swagger-php will create one automatically.

That means the above example would also work with just the OA\ExternalDocumentation annotation.

/**
+ * @OA\ExternalDocumentation(
+ *   description="More documentation here...",
+ *   url="https://example.com/externaldoc1/"
+ * )
+ */
+

Properties with union types

Sometimes properties or even lists (arrays) may contain data of different types. This can be expressed using oneOf.

/**
+ * @OA\Schema(
+ *      schema="StringList",
+ *      @OA\Property(property="value", type="array", @OA\Items(anyOf={@OA\Schema(type="string")}))
+ * )
+ * @OA\Schema(
+ *      schema="String",
+ *      @OA\Property(property="value", type="string")
+ * )
+ * @OA\Schema(
+ *      schema="Object",
+ *      @OA\Property(property="value", type="object")
+ * )
+ * @OA\Schema(
+ *     schema="mixedList",
+ *     @OA\Property(property="fields", type="array", @OA\Items(oneOf={
+ *         @OA\Schema(ref="#/components/schemas/StringList"),
+ *         @OA\Schema(ref="#/components/schemas/String"),
+ *         @OA\Schema(ref="#/components/schemas/Object")
+ *     }))
+ * )
+ */
+

This will resolve into this YAML

openapi: 3.0.0
+components:
+  schemas:
+    StringList:
+      properties:
+        value:
+          type: array
+          items:
+            anyOf:
+              -
+                type: string
+      type: object
+    String:
+      properties:
+        value:
+          type: string
+      type: object
+    Object:
+      properties:
+        value:
+          type: object
+      type: object
+    mixedList:
+      properties:
+        fields:
+          type: array
+          items:
+            oneOf:
+              -
+                $ref: '#/components/schemas/StringList'
+              -
+                $ref: '#/components/schemas/String'
+              -
+                $ref: '#/components/schemas/Object'
+      type: object
+

Referencing a security scheme

An API might have zero or more security schemes. These are defined at the top level and vary from simple to complex:

/**
+ * @OA\SecurityScheme(
+ *     type="apiKey",
+ *     name="api_key",
+ *     in="header",
+ *     securityScheme="api_key"
+ * )
+ *
+ * @OA\SecurityScheme(
+ *   type="oauth2",
+ *   securityScheme="petstore_auth",
+ *   @OA\Flow(
+ *      authorizationUrl="http://petstore.swagger.io/oauth/dialog",
+ *      flow="implicit",
+ *      scopes={
+ *         "read:pets": "read your pets",
+ *         "write:pets": "modify pets in your account"
+ *      }
+ *   )
+ * )
+ */
+

To declare an endpoint as secure and define what security schemes are available to authenticate a client it needs to be added to the operation, for example:

/**
+ * @OA\Get(
+ *      path="/api/secure/",
+ *      summary="Requires authentication"
+ *    ),
+ *    security={ {"api_key": {}} }
+ * )
+ */
+

Endpoints can support multiple security schemes and have custom options too:

/**
+ * @OA\Get(
+ *      path="/api/secure/",
+ *      summary="Requires authentication"
+ *    ),
+ *    security={
+ *      { "api_key": {} },
+ *      { "petstore_auth": {"write:pets", "read:pets"} }
+ *    }
+ * )
+ */
+

File upload with headers 

/**
+ * @OA\Post(
+ *   path="/v1/media/upload",
+ *   summary="Upload document",
+ *   description="",
+ *   tags={"Media"},
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @OA\MediaType(
+ *       mediaType="application/octet-stream",
+ *       @OA\Schema(
+ *         required={"content"},
+ *         @OA\Property(
+ *           description="Binary content of file",
+ *           property="content",
+ *           type="string",
+ *           format="binary"
+ *         )
+ *       )
+ *     )
+ *   ),
+ *   @OA\Response(
+ *     response=200, description="Success",
+ *     @OA\Schema(type="string")
+ *   ),
+ *   @OA\Response(
+ *     response=400, description="Bad Request"
+ *   )
+ * )
+ */
+

Set the XML root name

The OA\Xml annotation may be used to set the XML root element for a given @OA\XmlContent response body

/**
+ * @OA\Schema(
+ *     schema="Error",
+ *     @OA\Property(property="message"),
+ *     @OA\Xml(name="details")
+ * )
+ */
+
+/**
+ * @OA\Post(
+ *     path="/foobar",
+ *     @OA\Response(
+ *         response=400,
+ *         description="Request error",
+ *         @OA\XmlContent(ref="#/components/schemas/Error",
+ *           @OA\Xml(name="error")
+ *        )
+ *     )
+ * )
+ */
+

upload multipart/form-data

Form posts are @OA\Post requests with a multipart/form-data @OA\RequestBody. The relevant bit looks something like this

/**
+ * @OA\Post(
+ *   path="/v1/user/update",
+ *   summary="Form post",
+ *   @OA\RequestBody(
+ *     @OA\MediaType(
+ *       mediaType="multipart/form-data",
+ *       @OA\Schema(
+ *         @OA\Property(property="name"),
+ *         @OA\Property(
+ *           description="file to upload",
+ *           property="avatar",
+ *           type="string",
+ *           format="binary",
+ *         ),
+ *       )
+ *     )
+ *   ),
+ *   @OA\Response(response=200, description="Success")
+ * )
+ */
+

Default security scheme for all endpoints

Unless specified each endpoint needs to declare what security schemes it supports. However, there is a way to also configure security schemes globally for the whole API.

This is done on the @OA\OpenApi annotations:

Nested objects

Complex, nested data structures are defined by nesting @OA\Property annotations inside others (with type="object").

/**
+ *  @OA\Schema(
+ *    schema="Profile",
+ *    type="object",
+*
+ *    @OA\Property(
+ *      property="Status",
+ *      type="string",
+ *      example="0"
+ *    ),
+ *
+ *    @OA\Property(
+ *      property="Group",
+ *      type="object",
+ *
+ *      @OA\Property(
+ *        property="ID",
+ *        description="ID de grupo",
+ *        type="number",
+ *        example=-1
+ *      ),
+ *
+ *      @OA\Property(
+ *        property="Name",
+ *        description="Nombre de grupo",
+ *        type="string",
+ *        example="Superadmin"
+ *      )
+ *    )
+ *  )
+ */
+
+

Documenting union type response data using oneOf

A response with either a single or a list of QualificationHolder's.

/**
+ * @OA\Response(
+ *     response=200,
+ *     @OA\JsonContent(
+ *         oneOf={
+ *             @OA\Schema(ref="#/components/schemas/QualificationHolder"),
+ *             @OA\Schema(
+ *                 type="array",
+ *                 @OA\Items(ref="#/components/schemas/QualificationHolder")
+ *             )
+ *         }
+ *     )
+ * )
+ */
+

Reusing responses

Global responses are found under /components/responses and can be referenced/shared just like schema definitions (models)

/**
+ * @OA\Response(
+ *   response="product",
+ *   description="All information about a product",
+ *   @OA\JsonContent(ref="#/components/schemas/Product")
+ * )
+ */
+class ProductResponse {}
+
+ // ...
+
+class ProductController
+{
+    /**
+     * @OA\Get(
+     *   tags={"Products"},
+     *   path="/products/{product_id}",
+     *   @OA\Response(
+     *       response="default",
+     *       ref="#/components/responses/product"
+     *   )
+     * )
+     */
+    public function getProduct($id)
+    {
+    }
+}
+

`response` parameter is always required

Even if referencing a shared response definition, the response parameter is still required.

mediaType="/"

Using */* as mediaType is not possible using annotations.

Example:

/**
+ * @OA\MediaType(
+ *     mediaType="*/*",
+ *     @OA\Schema(type="string",format="binary")
+ * )
+ */
+

The doctrine annotations library used for parsing annotations does not handle this and will interpret the */ bit as the end of the comment.

Using just * or application/octet-stream might be usable workarounds.

Warning about Multiple response with same response="200"

There are two scenarios where this can happen

  1. A single endpoint contains two responses with the same response value.
  2. There are multiple global response declared, again more than one with the same response value.

Callbacks

The API does include basic support for callbacks. However, this needs to be set up mostly manually.

Example

/**
+ *     ...
+ *
+ *     callbacks={
+ *         "onChange"={
+ *              "{$request.query.callbackUrl}"={
+ *                  "post": {
+ *                      "requestBody": @OA\RequestBody(
+ *                          description="subscription payload",
+ *                          @OA\MediaType(mediaType="application/json", @OA\Schema(
+ *                              @OA\Property(property="timestamp", type="string", format="date-time", description="time of change")
+ *                          ))
+ *                      )
+ *                  },
+ *                  "responses": {
+ *                      "202": {
+ *                          "description": "Your server implementation should return this HTTP status code if the data was received successfully"
+ *                      }
+ *                  }
+ *              }
+ *         }
+ *     }
+ *
+ *     ...
+ *
+ */
+

(Mostly) virtual models

Typically, a model is annotated by adding a @OA\Schema annotation to the class and then individual @OA\Property annotations to the individually declared class properties.

It is possible, however, to nest O@\Property annotations inside a schema even without properties. In fact, all that is needed is a code anchor - e.g. an empty class.

use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    properties: [
+        'name' => new OA\Property(property: 'name', type: 'string'),
+        'email' => new OA\Property(property: 'email', type: 'string'),
+    ]
+)]
+class User {}
+

Using class name as type instead of references

Typically, when referencing schemas this is done using $ref's

#[OAT\Schema(schema: 'user')]
+class User
+{
+}
+
+#[OAT\Schema()]
+class Book
+{
+    /**
+     * @var User
+     */
+    #[OAT\Property(ref: '#/components/schemas/user')]
+    public $author;
+}
+

This works, but is not very convenient.

First, when using custom schema names (schema: 'user'), this needs to be taken into account everywhere. Secondly, having to write ref: '#/components/schemas/user' is tedious and error-prone.

Using attributes all this changes as we can take advantage of PHP itself by referring to a schema by its (fully qualified) class name.

With the same User schema as before, the Book::author property could be written in a few different ways

    #[OAT\Property()]
+    public User author;
+

or

    /**
+     * @var User
+     */
+    #[OAT\Property()]
+    public author;
+

or

    #[OAT\Property(type: User::class)]
+    public author;
+

Enums

As of PHP 8.1 there is native support for enum's.

swagger-php supports enums in much the same way as class names can be used to reference schemas.

Example

#[Schema()]
+enum State
+{
+    case OPEN;
+    case MERGED;
+    case DECLINED;
+}
+
+#[Schema()]
+class PullRequest
+   #[OAT\Property()]
+   public State $state
+}
+

However, in this case the schema generated for State will be an enum:

components:
+  schemas:
+    PullRequest:
+      properties:
+        state:
+          $ref: '#/components/schemas/State'
+      type: object
+    State:
+      type: string
+      enum:
+        - OPEN
+        - MERGED
+        - DECLINED
+

Multi value query parameter: &q[]=1&q[]=1

PHP allows to have query parameters multiple times in the url and will combine the values to an array if the parameter name uses trailing []. In fact, it is possible to create nested arrays too by using more than one pair of [].

In terms of OpenAPI, the parameters can be considered a single parameter with a list of values.

/**
+ * @OA\Get(
+ *     path="/api/endpoint",
+ *     description="The endpoint",
+ *     operationId="endpoint",
+ *     tags={"endpoints"},
+ *     @OA\Parameter(
+ *         name="things[]",
+ *         in="query",
+ *         description="A list of things.",
+ *         required=false,
+ *         @OA\Schema(
+ *             type="array",
+ *             @OA\Items(type="integer")
+ *         )
+ *     ),
+ *     @OA\Response(response="200", description="All good")
+ * )
+ */
+

The corresponding bit of the spec will look like this:

      parameters:
+        -
+          name: 'things[]'
+          in: query
+          description: 'A list of things.'
+          required: false
+          schema:
+            type: array
+            items:
+              type: integer
+

swagger-ui will show a form that allows to add/remove items (integer values in this case) to/from a list and post those values as something like ?things[]=1&things[]=2&things[]=0

Custom response classes

Even with using refs there is a bit of overhead in sharing responses. One way around that is to write your own response classes. The beauty is that in your custom __construct() method you can prefill as much as you need.

Best of all, this works for both annotations and attributes.

Example:

use OpenApi\Attributes as OA;
+
+/**
+ * @Annotation
+ */
+#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
+class BadRequest extends OA\Response
+{
+    public function __construct()
+    {
+        parent::__construct(response: 400, description: 'Bad request');
+    }
+}
+
+class Controller
+{
+
+    #[OA\Get(path: '/foo', responses: [new BadRequest()])]
+    public function get()
+    {
+    }
+
+    #[OA\Post(path: '/foo')]
+    #[BadRequest]
+    public function post()
+    {
+    }
+
+    /**
+     * @OA\Delete(
+     *     path="/foo",
+     *     @BadRequest()
+     * )
+     */
+    public function delete()
+    {
+    }
+}
+

Annotations only?

If you are only interested in annotations you canleave out the attribute setup line (#[\Attribute...) for BadRequest.

Furthermore, your custom annotations should extend from the OpenApi\Annotations namespace.

Annotating class constants 

use OpenApi\Attributes as OA;
+
+#[OA\Schema()]
+class Airport
+{
+    #[OA\Property(property='kind')]
+    public const KIND = 'Airport';
+}
+

The const property is supported in OpenApi 3.1.0.

components:
+  schemas:
+    Airport:
+        properties:
+          kind:
+            type: string
+            const: Airport
+

For 3.0.0 this is serialized into a single value enum.

components:
+  schemas:
+    Airport:
+        properties:
+          kind:
+            type: string
+            enum:
+              - Airport
+
+ + + + + \ No newline at end of file diff --git a/guide/faq.html b/guide/faq.html new file mode 100644 index 000000000..bec7d1380 --- /dev/null +++ b/guide/faq.html @@ -0,0 +1,108 @@ + + + + + + FAQ | Swagger-PHP + + + + + + + + + +
Swagger-PHP

FAQ

Warning: Required @OA\Info() not found

With adding support for PHP attributes in version 4, some architectural changes had to be made.

One of those changes is that placing annotations in your source files is now subject to the same limitations as attributes. These limits are dictated by the PHP reflection API, specifically where it provides access to attributes and doc comments.

This means stand-alone annotations are no longer supported and ignored as swagger-php cannot "see" them any more.

Supported locations:

  • class
  • interface
  • trait
  • method
  • property
  • class/interface const

Most commonly this manifests with a warning about the required @OA\Info not being found. While most annotations have specific related code, the info annotation (and a few more) is kind of global.

The simplest solution to avoid this issue is to add a 'dummy' class to the docblock and add all 'global' annotations (e.g. Tag, Server, SecurityScheme, etc.) in a single docblock to that class.

/**
+ * @OA\Tag(
+ *     name="user",
+ *     description="User related operations"
+ * )
+ * @OA\Info(
+ *     version="1.0",
+ *     title="Example API",
+ *     description="Example info",
+ *     @OA\Contact(name="Swagger API Team")
+ * )
+ * @OA\Server(
+ *     url="https://example.localhost",
+ *     description="API server"
+ * )
+ */
+class OpenApiSpec
+{
+}
+

As of version 4.8 the doctrine/annotations library is optional and might cause the same message.

If this is the case, doctrine annotations must be installed separately:

composer require doctrine/annotations
+

Annotations missing

Another side effect of using reflection is that swagger-php "can't see" multiple consecutive docblocks any more as the PHP reflection API only provides access to the docblock closest to a given structural element.

class Controller
+{
+    /**
+     * @OA\Delete(
+     *      path="/api/v0.0.2/notifications/{id}",
+     *      operationId="deleteNotificationById",
+     *      summary="Delete notification by ID",
+     *      @OA\Parameter(name="id", in="path", @OA\Schema(type="integer")),
+     *      @OA\Response(response=200, description="OK"),
+     *      @OA\Response(response=400, description="Bad Request")
+     * )
+     */
+    /**
+     * Delete notification by ID.
+     *
+     * @param Request $request
+     * @param AppNotification $notification
+     *
+     * @return Response
+     * @throws Exception
+     */
+    public function destroy(Request $request, AppNotification $notification) {
+        //
+    }
+}
+

In this case the simplest solution is to merge both docblocks. As an additional benefit the duplication of the summary can be avoided.

In this improved version swagger-php will automatically use the docblock summary just as explicitly done above.

class Controller
+{
+    /**
+     * Delete notification by ID.
+     *
+     * @OA\Delete(
+     *      path="/api/v0.0.2/notifications/{id}",
+     *      operationId="deleteNotificationById",
+     *      @OA\Parameter(name="id", in="path", @OA\Schema(type="integer")),
+     *      @OA\Response(response=200, description="OK"),
+     *      @OA\Response(response=400, description="Bad Request")
+     * )
+     *
+     * @param Request $request
+     * @param AppNotification $notification
+     *
+     * @return Response
+     * @throws Exception
+     */
+    public function destroy(Request $request, AppNotification $notification) {
+        //
+    }
+}
+

Resulting spec:

openapi: 3.0.0
+paths:
+  '/api/v0.0.2/notifications/{id}':
+    delete:
+      summary: 'XDelete notification by ID.'
+      operationId: deleteNotificationById
+      parameters:
+        -
+          name: id
+          in: path
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: OK
+        '400':
+          description: 'Bad Request'
+
+

Skipping unknown \SomeClass

This message means that swagger-php has tried to use reflection to inspect \SomeClass and that PHP could not find/load that class. Effectively, this means that class_exists("\SomeClass") returns false.

Using the -b --bootstrap option

There are a number of reasons why this could happen. If you are using the openapi command line tool from a global installation typically the application classloader (composer) is not active. With you application root being myapp you could try:

openapi -b myapp/vendor/autoload.php myapp/src
+

The -b allows to execute some extra PHP code to load whatever is needed to register your apps classloader with PHP.

Namespace mismatch

Another reason for this error could be that your class actually has the wrong namespace (or no namespace at all!).

Depending on your framework this might still work in the context of your app, but the composer autoloader alone might not be able to load your class (assuming you are using composer).

No output from openapi command line tool

Depending on your PHP configuration, running the openapi command line tool might result in no output at all.

The reason for this is that openapi currently uses the error_log function for all output.

So if this is configured to write to a file, then it will seem like the command is broken.

+ + + + + \ No newline at end of file diff --git a/guide/generating-openapi-documents.html b/guide/generating-openapi-documents.html new file mode 100644 index 000000000..42ad56670 --- /dev/null +++ b/guide/generating-openapi-documents.html @@ -0,0 +1,50 @@ + + + + + + Generating OpenAPI documents | Swagger-PHP + + + + + + + + + +
Swagger-PHP

Generating OpenAPI documents

./bin/openapi

swagger-php includes a command line tool ./bin/openapi. This can be used to generate OpenAPI documents.

> ./vendor/bin/openapi app -o openapi.yaml
+

Output Format

By default the output format is YAML. If a filename is given (via --output or -o) the tool will use the file extension to determine the format.

The --format option can be used to force a specific format.

For a list of all available options use the -h option

> ./bin/openapi -h
+
+Usage: openapi [--option value] [/path/to/project ...]
+
+Options:
+  --config (-c)     Generator config
+                    ex: -c operationId.hash=false
+  --legacy (-l)     Use legacy TokenAnalyser; default is the new ReflectionAnalyser
+  --output (-o)     Path to store the generated documentation.
+                    ex: --output openapi.yaml
+  --exclude (-e)    Exclude path(s).
+                    ex: --exclude vendor,library/Zend
+  --pattern (-n)    Pattern of files to scan.
+                    ex: --pattern "*.php" or --pattern "/\.(phps|php)$/"
+  --bootstrap (-b)  Bootstrap a php file for defining constants, etc.
+                    ex: --bootstrap config/constants.php
+  --processor (-p)  Register an additional processor.
+  --format (-f)     Force yaml or json.
+  --debug (-d)      Show additional error information.
+  --version         The OpenAPI version; defaults to 3.0.0.
+  --help (-h)       Display this help message.
+

Using PHP

Depending on your use case PHP code can also be used to generate OpenAPI documents in a more dynamic way.

In its simplest form this may look something like

<?php
+require("vendor/autoload.php");
+
+$openapi = \OpenApi\Generator::scan(['/path/to/project']);
+
+header('Content-Type: application/x-yaml');
+echo $openapi->toYaml();
+

Programming API

Details about the swagger-php API can be found in the reference.

+ + + + + \ No newline at end of file diff --git a/guide/index.html b/guide/index.html new file mode 100644 index 000000000..c555a7704 --- /dev/null +++ b/guide/index.html @@ -0,0 +1,21 @@ + + + + + + What is Swagger-PHP? | Swagger-PHP + + + + + + + + + +
Swagger-PHP

What is Swagger-PHP?

swagger-php is a library that extracts API metadata from your PHP source code files.

The idea is to add swagger-php annotations or attributes next to the relevant PHP code in your application. These will contain the details about your API and swagger-php will convert those into machine-readable OpenAPI documentation.

By adding your API documentation next to the corresponding source code (same file!) makes it easy to keep it up-to-date as all details can be modified in one place.

Annotating vs. Annotations

When talking about annotating your code we mean the act of adding meta-data to your codebase. This can be done by either adding Annotations or Attributes.

Requirements

Using swagger-php requires a minimum of PHP 7.2 for using annotations and at least PHP 8.1 to use attributes.

+ + + + + \ No newline at end of file diff --git a/guide/installation.html b/guide/installation.html new file mode 100644 index 000000000..0268ba9da --- /dev/null +++ b/guide/installation.html @@ -0,0 +1,23 @@ + + + + + + Installation | Swagger-PHP + + + + + + + + + +
Swagger-PHP

Installation

Per project

We recommend adding swagger-php to your project using Composer

> composer require zircote/swagger-php
+

Globally

Alternatively, use the composer global argument to install swagger-php globally.

> composer global require zircote/swagger-php
+

PATH variables

Remember to add the ~/.composer/vendor/bin directory to the PATH in your environment.

+ + + + + \ No newline at end of file diff --git a/guide/migrating-to-v3.html b/guide/migrating-to-v3.html new file mode 100644 index 000000000..05730425a --- /dev/null +++ b/guide/migrating-to-v3.html @@ -0,0 +1,21 @@ + + + + + + Migrating to v3 | Swagger-PHP + + + + + + + + + +
Swagger-PHP

Migrating to v3

Swagger-PHP 3.x generates an openapi.json file that follows the OpenAPI Version 3.0.x Specification.

If you need to output the older 2.x specification use OpenApi-php 2.x

The default output changed from json to yaml

This aligns better with the direction of the swagger documentation and examples. Annotations can't be used as string anymore, you'll need to call toYaml() or toJson() if you prefer the json format.

Updated CLI

  • Added colors
  • No output for successful execution (Removed summary)
  • non-zero exit when an error occurred.
  • Defaults to yaml
  • Defaults to stdout. To save to openapi.yaml use -o or >

Changed annotations

SWG is renamed to OA

The namespace is renamed from SWG (Swagger) to OA (OpenApi)

@SWG\Swagger() is renamed to @OA\OpenApi()

@SWG\Path() is renamed to @OA\PathItem()

The specification uses the term "Path Item Object", updated the annotation to reflect that.

@SWG\Definition() is removed

Use @OA\Schema() instead of @OA\Definition() and update the references from "#/definitions/something" to "#/components/schemas/something".

@SWG\Path is removed

Use @OA\PathItem instead of @SWG\Path and update references.

Consumes, produces field is removed from OpenAPI specification

Use @OA\MediaType to set data format.

Rename parameter references

Rename #/parameters/{parameter_name} to #/components/parameters/{parameter_name}

Rename response references

Rename #/responses/{response} to #/components/responses/{response}

Renamed cli

Renamed swagger to openapi

More details about differences:

A Visual Guide to What's New in Swagger 3.0

+ + + + + \ No newline at end of file diff --git a/guide/migrating-to-v4.html b/guide/migrating-to-v4.html new file mode 100644 index 000000000..8355b9a32 --- /dev/null +++ b/guide/migrating-to-v4.html @@ -0,0 +1,68 @@ + + + + + + Migrating to v4 | Swagger-PHP + + + + + + + + + +
Swagger-PHP

Migrating to v4

Overview

  • As of PHP 8.1 annotations may be used as PHP attributes instead. That means all references to annotations in this document also apply to attributes.
  • Annotations now must be associated with a structural element (class, trait, interface), a method, property or const.
  • A new annotation PathParameter was added for improved framework support.
  • A new annotation Attachable was added to simplify custom processing. Attachable can be used to attach arbitrary data to any given annotation.
  • Deprecated elements have been removed
    • \Openapi\Analysis::processors()
    • \Openapi\Analyser::$whitelist
    • \Openapi\Analyser::$defaultImports
    • \Openapi\Logger
  • Legacy support is available via the previous TokenAnalyser
  • Improvements to the Generator class

Annotations as PHP attributes

While PHP attributes have been around since PHP 8.0 they were lacking the ability to be nested. This changes with PHP 8.1 which allows to use new in initializers.

Swagger-php attributes also make use of named arguments, so attribute parameters can be (mostly) typed. There are some limitations to type hints which can only be resolved once support for PHP 7.x is dropped.

Using annotations 


+use OpenApi\Annotations as OA;
+
+/**
+ * @OA\Info(
+ *   version="1.0.0",
+ *   title="My API",
+ *   @OA\License(name="MIT"),
+ *   @OA\Attachable()
+ * )
+ */
+class OpenApiSpec
+{
+}
+

Using attributes 


+use OpenApi\Attributes as OA;
+
+#[OA\Info(
+    version: '1.0.0',
+    title: 'My API',
+    attachables: [new OA\Attachable()]
+)]
+#[OA\License(name: 'MIT')]
+class OpenApiSpec
+{
+}
+

Optional nesting

One of the few differences between annotations and attributes visible in the above example is that the OA\License attribute is not nested within OA\Info. Nesting of attributes is possible and required in certain cases however, in cases where there is no ambiguity attributes may be all written on the top level and swagger-php will do the rest.

Annotations must be associated with a structural element

The (now legacy) way of parsing PHP files meant that docblocks could live in a file without a single line of actual PHP code.

PHP Attributes cannot exist in isolation; they need code to be associated with and then are available via reflection on the associated structural element. In order to allow to keep supporting annotations and the code simple it made sense to treat annotations and attributes the same in this respect.

The PathParameter annotation

As annotation this is just a short form for

   @OA\Parameter(in='body')
+

Things get more interesting when it comes to using it as attribute, though. In the context of a controller you can now do something like

class MyController
+{
+    #[OA\Get(path: '/products/{product_id}')]
+    public function getProduct(
+        #[OA\PathParameter] string $product_id)
+    {
+    }
+}
+

Here it avoids having to duplicate details about the $product_id parameter and the simple use of the attribute will pick up typehints automatically.

The Attachable annotation

Technically these were added in version 3.3.0, however they become really useful only with version 4.

The attachable annotation is similar to the OpenApi vendor extension x=. The main difference are that

  1. Attachables allow complex structures and strong typing
  2. Attachables are not added to the generated spec.

Their main purpose is to make customizing swagger-php easier by allowing to add arbitrary data to any annotation.

One possible use case could be custom annotations. Classes extending Attachable are allowed to limit the allowed parent annotations. This means it would be easy to create a new attribute to flag certain endpoints as private and exclude them under certain conditions from the spec (via a custom processor).

Removed deprecated elements

\Openapi\Analysis::processors()

Processors have been moved into the Generator class incl. some new convenience methods.

\Openapi\Analyser::$whitelist

This has been replaced with the Generator namespaces property.

\Openapi\Analyser::$defaultImports

This has been replaced with the Generator aliases property.

\Openapi\Logger

This class has been removed completely. Instead, you may configure a PSR-3 logger.

Improvements to the Generator class

The removal of deprecated static config options means that the Generator class now is the main entry point into swagger-php when used programmatically.

To make the migration as simple as possible a new Generator::withContext(callable) has been added. This allows to use parts of the library (an Analyser instance, for example) within the context of a Generator instance.

Example:

$analyser = createMyAnalyser();
+
+$analysis = (new Generator())
+    ->addAlias('fo', 'My\\Attribute\\Namespace')
+    ->addNamespace('Other\\Annotations\\')
+    ->withContext(function (Generator $generator, Analysis $analysis, Context $context) use ($analyser) {
+        $analyser->setGenerator($generator);
+        $analysis = $analyser->fromFile('my_code.php', $context);
+        $analysis->process($generator->getProcessors());
+
+        return $analysis;
+    });
+
+ + + + + \ No newline at end of file diff --git a/guide/required-elements.html b/guide/required-elements.html new file mode 100644 index 000000000..c6b07485f --- /dev/null +++ b/guide/required-elements.html @@ -0,0 +1,86 @@ + + + + + + Required elements | Swagger-PHP + + + + + + + + + +
Swagger-PHP

Required elements

The OpenAPI specification defines a minimum set of information for a valid document.

For the most part that consists of some general information about the API like name, version and at least one endpoint.

The endpoint, in turn, needs to have a path and at least one response.

Minimum required annotations

With the above in mind a minimal API with a single endpoint could look like this

with the resulting OpenAPI document like this

openapi: 3.0.0
+info:
+  title: 'My First API'
+  version: '0.1'
+paths:
+  /api/data.json:
+    get:
+      operationId: 236f26ae21b015a60adbce41f8f316e3
+      responses:
+        '200':
+          description: 'The data'
+

Code locations

Attributes and annotations can be added anywhere on declarations in code as defined by the PHP docs. These are limited to the extent of what the PHP Reflection APIs supports.

Optional elements

Looking at the generated document you will notice that there are some elements that swagger-php adds automatically when they are missing.

For the most part those are @OA\OpenApi, @OA\Components and @OA\PathItem.

+ + + + + \ No newline at end of file diff --git a/guide/under-the-hood.html b/guide/under-the-hood.html new file mode 100644 index 000000000..6b682bbf0 --- /dev/null +++ b/guide/under-the-hood.html @@ -0,0 +1,23 @@ + + + + + + Under the hood | Swagger-PHP + + + + + + + + + +
Swagger-PHP

Under the hood

Processing flow

  • The Generator iterates over the given sources (Symfony Finder, file/directory list, etc)
  • The configured analyser (AnalyserInterface) reads the files and builds an Analysis object. Default (as of v4) is the ReflectionAnalyser. Alternatively, there is the TokenAnalyser which was the default in v3.
  • The Analysis object and its annotations are then processed by the configured processors.
  • If enabled, the analysis/annotations are validated.
  • The root OpenApi annotation then contains all annotations and is serialized into YAML/JSON.

Context

Each annotation is associated with a unique Context instance. This contains details, collected by the parser/analyser, about the PHP context where the annotation was found.

Typically, there will be a processor that uses the data to augment/enrich the annotation.

Examples of the data collected:

  • class/interface/trait/enum names
  • property names
  • doctype or native type hints
  • file name and line number

Analysis

Contains all detected annotations and other relevant meta-data.

It uses a SplObjectStorage instance to store the parsed annotations.

Documentation

This documentation is generated with VitePress

Installation 

cd docs
+npm install vitepress 
+

Workflow

  • Edit .md files in the docs folder
  • Update annotation / attribute PHP docblocks.
    These will be extracted during publishing into the reference section.
  • Run 'composer docs:build' to check for any errors
  • Run 'composer docs:dev' to test the generated documentation locally (localhost:3000)
  • Create PR and update master
  • Manually trigger the gh-pages workflow to update the online docs.

The last step requires commit rights on zircote/swagger-php.

+ + + + + \ No newline at end of file diff --git a/hashmap.json b/hashmap.json new file mode 100644 index 000000000..9dff1d065 --- /dev/null +++ b/hashmap.json @@ -0,0 +1 @@ +{"guide_annotations.md":"b48e8efc","guide_attributes.md":"b0468df2","guide_common-techniques.md":"c3d11b39","guide_cookbook.md":"58253880","guide_faq.md":"818b1e6e","guide_generating-openapi-documents.md":"4e871b91","guide_index.md":"2455f0b6","guide_installation.md":"c1a9b9e5","guide_migrating-to-v3.md":"f8a7ce6f","guide_migrating-to-v4.md":"5a3b1acb","guide_required-elements.md":"13284533","guide_under-the-hood.md":"19c62cc3","index.md":"59a0a95e","reference_annotations.md":"cdba131a","reference_attributes.md":"e96acd84","reference_generator.md":"681f1e2d","reference_index.md":"c170f535","reference_processors.md":"6f2ce137","related-projects.md":"2420d622"} diff --git a/index.html b/index.html new file mode 100644 index 000000000..95ed03482 --- /dev/null +++ b/index.html @@ -0,0 +1,77 @@ + + + + + + Swagger-PHP + + + + + + + + + +
Swagger-PHP

Swagger-PHP

Generate OpenAPI documentation for your RESTful API.

User Guide →

OpenAPI conformant

Generate OpenAPI documents in version 3.0 or 3.1.

Document your API inside PHP source code

Using swagger-php lets you write the API documentation inside the PHP source files which helps keeping the documentation up-to-date.

Annotation and Attribute support

Annotations can be either docblocks or PHP 8.1 attributes.

1. Install with composer: 

> composer require zircote/swagger-php
+

2. Update your code

Add swagger-php annotations or attributes to your source code.

3. Generate OpenAPI documentation 

> ./bin/openapi src -o openapi.yaml
+

4. Explore and interact with your API

Use an OpenAPI tool like Swagger UI to explore and interact with your API.

+ + + + + \ No newline at end of file diff --git a/reference/annotations.html b/reference/annotations.html new file mode 100644 index 000000000..abbdf1330 --- /dev/null +++ b/reference/annotations.html @@ -0,0 +1,21 @@ + + + + + + Annotations | Swagger-PHP + + + + + + + + + +
Swagger-PHP

Annotations

This page is generated automatically from the swagger-php sources.

For improvements head over to GitHub and create a PR 😉

In addition to this page, there are also a number of examples which might help you out.

AdditionalProperties

Allowed in

Schema, Property, Items, JsonContent, XmlContent, AdditionalProperties

Nested elements

Discriminator, Items, Property, ExternalDocumentation, Xml, AdditionalProperties, Attachable

Attachable

A container for custom data to be attached to an annotation.

These will be ignored by swagger-php but can be used for custom processing.

Allowed in

AdditionalProperties, Components, Contact, Delete, Discriminator, Examples, ExternalDocumentation, Flow, Get, Head, Header, Info, Items, JsonContent, License, Link, MediaType, OpenApi, Operation, Options, Parameter, Patch, PathItem, PathParameter, Post, Property, Put, RequestBody, Response, Schema, SecurityScheme, Server, ServerVariable, Tag, Trace, Webhook, Xml, XmlContent

Components

Holds a set of reusable objects for different aspects of the OA.

All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.

Allowed in

OpenApi

Nested elements

Response, Parameter, PathParameter, RequestBody, Examples, Header, SecurityScheme, Link, Schema, Attachable

Properties

callbacks : array

Reusable Callbacks.

Reference

Contact

Contact information for the exposed API.

Allowed in

Info

Nested elements

Attachable

Properties

name : string

The identifying name of the contact person/organization.

url : string

The URL pointing to the contact information.

email : string

The email address of the contact person/organization.

Reference

CookieParameter

A @OA\Request cookie parameter.

Allowed in

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements

Schema, Examples, Attachable

Properties

in

This takes 'cookie' as the default location.

Delete

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Properties

method

No details available.

Discriminator

The discriminator is a specific object in a schema which is used to inform the consumer of the specification of an alternative schema based on the value associated with it.

This object is based on the JSON Schema Specification and uses a predefined subset of it. On top of this subset, there are extensions provided by this specification to allow for more complete documentation.

Allowed in

Schema, Property, AdditionalProperties, Items, JsonContent, XmlContent

Nested elements

Attachable

Properties

propertyName : string

The name of the property in the payload that will hold the discriminator value.

mapping : string[]

An object to hold mappings between payload values and schema names or references.

Reference

Examples

Allowed in

Components, Schema, Parameter, PathParameter, MediaType, JsonContent, XmlContent

Nested elements

Attachable

Properties

ref : string|class-string|object

The relative or absolute path to an example.

See: Using refs

example : string

The key into `#/components/examples`.

summary : string

Short description for the example.

description : string

Embedded literal example.

The value field and externalValue field are mutually exclusive.

To represent examples of media types that cannot naturally be represented
in JSON or YAML, use a string value to contain the example, escaping where necessary.

value : int|string|array

Embedded literal example.

The value field and externalValue field are mutually exclusive.

To represent examples of media types that cannot naturally be represented
in JSON or YAML, use a string value to contain the example, escaping where necessary.

externalValue : string

An URL that points to the literal example.

This provides the capability to reference examples that cannot easily be included
in JSON or YAML documents.

The value field and externalValue field are mutually exclusive.

ExternalDocumentation

Allows referencing an external resource for extended documentation.

Allowed in

OpenApi, Tag, Schema, AdditionalProperties, Property, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace, Items, JsonContent, XmlContent

Nested elements

Attachable

Properties

description : string

A short description of the target documentation. GFM syntax can be used for rich text representation.

url : string

The URL for the target documentation.

Reference

Flow

Configuration details for a supported OAuth Flow.

Allowed in

SecurityScheme

Nested elements

Attachable

Properties

authorizationUrl : string

The authorization url to be used for this flow.

This must be in the form of an url.

tokenUrl : string

The token URL to be used for this flow.

This must be in the form of an url.

refreshUrl : string

The URL to be used for obtaining refresh tokens.

This must be in the form of an url.

flow : string

Flow name.

One of ['implicit', 'password', 'authorizationCode', 'clientCredentials'].

scopes : array

The available scopes for the OAuth2 security scheme.

A map between the scope name and a short description for it.

Reference

Get

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Properties

method

No details available.

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Properties

method

No details available.

Allowed in

Components, Response

Nested elements

Schema, Attachable

Properties

ref : string|class-string|object

The relative or absolute path to the endpoint.

See: Using refs

header : string

No details available.

description : string

A brief description of the parameter.

This could contain examples of use.
CommonMark syntax MAY be used for rich text representation.

required : bool

No details available.

deprecated : bool

Specifies that a parameter is deprecated and SHOULD be transitioned out of usage.

allowEmptyValue : bool

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored.

Reference

HeaderParameter

A @OA\Request header parameter.

Allowed in

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements

Schema, Examples, Attachable

Properties

in

This takes 'header' as the default location.

Info

The object provides metadata about the API.

The metadata may be used by the clients if needed and may be presented in editing or documentation generation tools for convenience.

Allowed in

OpenApi

Nested elements

Contact, License, Attachable

Properties

title : string

The title of the application.

description : string

A short description of the application.

CommonMark syntax may be used for rich text representation.

termsOfService : string

An URL to the Terms of Service for the API.

Must be in the format of an url.

version : string

The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).

Reference

Items

The description of an item in a Schema with type array.

Allowed in

Property, AdditionalProperties, Schema, JsonContent, XmlContent, Items

Nested elements

Discriminator, Items, Property, ExternalDocumentation, Xml, AdditionalProperties, Attachable

JsonContent

Shorthand for a json response.

Use as @OA\Schema inside a Response and MediaType->'application/json' will be generated.

Nested elements

Discriminator, Items, Property, ExternalDocumentation, AdditionalProperties, Examples, Attachable

License

License information for the exposed API.

Allowed in

Info

Nested elements

Attachable

Properties

name : string

The license name used for the API.

identifier : string

An SPDX license expression for the API. The `identifier` field is mutually exclusive of the `url` field.

url : string

An URL to the license used for the API. This MUST be in the form of a URL.

The `url` field is mutually exclusive of the `identifier` field.

Reference

The Link object represents a possible design-time link for a response.

The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations.

Unlike dynamic links (i.e. links provided in the response payload), the OA linking mechanism does not require link information in the runtime response.

For computing links, and providing instructions to execute them, a runtime expression is used for accessing values in an operation and using them as parameters while invoking the linked operation.

Allowed in

Components, Response

Nested elements

Server, Attachable

Properties

ref : string|class-string|object

No details available.

See: Using refs

link : string

The key into MediaType->links array.

operationRef : string

A relative or absolute reference to an OA operation.

This field is mutually exclusive of the operationId field, and must point to an Operation object.

Relative values may be used to locate an existing Operation object in the OpenAPI definition.

operationId : string

The name of an existing, resolvable OA operation, as defined with a unique operationId.

This field is mutually exclusive of the operationRef field.

parameters : array<string,mixed>

A map representing parameters to pass to an operation as specified with operationId or identified via
operationRef.

The key is the parameter name to be used, whereas the value can be a constant or an expression to
be evaluated and passed to the linked operation.
The parameter name can be qualified using the parameter location [{in}.]{name} for operations
that use the same parameter name in different locations (e.g. path.id).

requestBody

A literal value or {expression} to use as a request body when calling the target operation.

description : string

A description of the link.

CommonMark syntax may be used for rich text representation.

Reference

MediaType

Each Media Type object provides schema and examples for the media type identified by its key.

Allowed in

Response, RequestBody

Nested elements

Schema, Examples, Attachable

Properties

mediaType : string

The key into Operation->content array.

example

Example of the media type.

The example object should be in the correct format as specified by the media type.
The example object is mutually exclusive of the examples object.

Furthermore, if referencing a schema which contains an example,
the example value shall override the example provided by the schema.

encoding : array<string,mixed>

A map between a property name and its encoding information.

The key, being the property name, must exist in the schema as a property.

The encoding object shall only apply to requestBody objects when the media type is multipart or
application/x-www-form-urlencoded.

Reference

OpenApi

This is the root document object for the API specification.

Nested elements

Info, Server, PathItem, Components, Tag, ExternalDocumentation, Webhook, Attachable

Properties

openapi : string

The semantic version number of the OpenAPI Specification version that the OpenAPI document uses.

The openapi field should be used by tooling specifications and clients to interpret the OpenAPI document.

A version specified via `Generator::setVersion()` will overwrite this value.

This is not related to the API info::version string.

security : array

A declaration of which security mechanisms can be used across the API.

The list of values includes alternative security requirement objects that can be used.
Only one of the security requirement objects need to be satisfied to authorize a request.
Individual operations can override this definition.
To make security optional, an empty security requirement `({})` can be included in the array.

Reference

Options

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Properties

method

No details available.

Parameter

Describes a single operation parameter.

A unique parameter is defined by a combination of a name and location.

Allowed in

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements

Schema, Examples, Attachable

Properties

ref : string|class-string|object

The relative or absolute path to the endpoint.

See: Using refs

parameter : string

The key into Components::parameters or PathItem::parameters array.

name : string

The (case-sensitive) name of the parameter.

If in is "path", the name field must correspond to the associated path segment from the path field in the Paths Object.

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition shall be ignored.
For all other cases, the name corresponds to the parameter name used by the in property.

in : string

The location of the parameter.

Possible values are "query", "header", "path" or "cookie".

description : string

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

required : bool

Determines whether this parameter is mandatory.

If the parameter location is "path", this property is required and its value must be true.
Otherwise, the property may be included and its default value is false.

deprecated : bool

Specifies that a parameter is deprecated and should be transitioned out of usage.

allowEmptyValue : bool

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue shall be ignored.

style : string

Describes how the parameter value will be serialized depending on the type of the parameter value.

Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

explode : bool

When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.

For other types of parameters this property has no effect.

When style is form, the default value is true.
For all other styles, the default value is false.

allowReserved : bool

Determines whether the parameter value should allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.

This property only applies to parameters with an in value of query.

The default value is false.

example

Example of the media type.

The example should match the specified schema and encoding properties if present.
The example object is mutually exclusive of the examples object.
Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema.
To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

content : array<MediaType>|JsonContent|XmlContent|Attachable

A map containing the representations for the parameter.

The key is the media type and the value describes it.
The map must only contain one entry.

matrix

Path-style parameters defined by RFC6570.

See: RFC6570

label

Label style parameters defined by RFC6570.

See: RFC6570

form

Form style parameters defined by RFC6570.

This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.

See: RFC6570

simple : array

Simple style parameters defined by RFC6570.

This option replaces collectionFormat with a csv value from OpenAPI 2.0.

See: RFC6570

spaceDelimited : array

Space separated array values.

This option replaces collectionFormat equal to ssv from OpenAPI 2.0.

pipeDelimited : array

Pipe separated array values.

This option replaces collectionFormat equal to pipes from OpenAPI 2.0.

deepObject

Provides a simple way of rendering nested objects using form parameters.

Reference

Patch

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Properties

method

No details available.

PathItem

Describes the operations available on a single path.

A Path Item may be empty, due to ACL constraints. The path itself is still exposed to the documentation viewer, but they will not know which operations and parameters are available.

Allowed in

OpenApi

Nested elements

Get, Post, Put, Delete, Patch, Trace, Head, Options, Parameter, PathParameter, Server, Attachable

Properties

ref : string|class-string|object

No details available.

See: Using refs

summary : string

An optional, string summary, intended to apply to all operations in this path.

description : string

An optional, string description, intended to apply to all operations in this path.

path : string

Key for the Path Object (OpenApi->paths array).

Reference

PathParameter

A @OA\Request path parameter.

Allowed in

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements

Schema, Examples, Attachable

Properties

in

This takes 'path' as the default location.

required

No details available.

Post

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Properties

method

No details available.

Property

Allowed in

AdditionalProperties, Schema, JsonContent, XmlContent, Property, Items

Nested elements

Discriminator, Items, Property, ExternalDocumentation, Xml, AdditionalProperties, Attachable

Properties

property : string

The key into Schema->properties array.

Put

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Properties

method

No details available.

QueryParameter

A @OA\Request query parameter.

Allowed in

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements

Schema, Examples, Attachable

Properties

in

This takes 'query' as the default location.

RequestBody

Describes a single request body.

Allowed in

Components, Delete, Get, Head, Operation, Options, Patch, Post, Trace, Put

Nested elements

MediaType, Attachable

Properties

ref : string|class-string|object

The relative or absolute path to a request body.

See: Using refs

request : string

The key into Components->requestBodies array.

description : string

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

required : bool

Determines whether this parameter is mandatory.

If the parameter location is "path", this property is required and its value must be true.
Otherwise, the property may be included and its default value is false.

Reference

Response

Describes a single response from an API Operation, including design-time, static links to operations based on the response.

Allowed in

Components, Operation, Get, Post, Put, Patch, Delete, Head, Options, Trace

Nested elements

MediaType, Header, Link, Attachable

Properties

ref : string|class-string|object

The relative or absolute path to a response.

See: Using refs

response : string|int

The key into Operations->responses array.

A HTTP status code or default.

description : string

A short description of the response.

CommonMark syntax may be used for rich text representation.

Reference

Schema

The definition of input and output data types.

These types can be objects, but also primitives and arrays.

This object is based on the JSON Schema Specification and uses a predefined subset of it. On top of this subset, there are extensions provided by this specification to allow for more complete documentation.

Allowed in

Components, Parameter, PathParameter, MediaType, Header

Nested elements

Discriminator, Items, Property, ExternalDocumentation, Examples, Xml, AdditionalProperties, Attachable

Properties

ref : string|class-string|object

The relative or absolute path to the endpoint.

See: Using refs

schema : string

The key into Components->schemas array.

title : string

Can be used to decorate a user interface with information about the data produced by this user interface.

Preferably short; use description for more details.

description : string

A description will provide explanation about the purpose of the instance described by this schema.

maxProperties : int

The maximum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is less than, or equal to, the
value of this attribute.

minProperties : int

The minimum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is greater than, or equal to, the
value of this attribute.

required : string[]

An object instance is valid against this property if its property set contains all elements in this property's
array value.

type : string|non-empty-array<string>

The type of the schema/property.

OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".

Since OpenApi v3.1 an array of types may be used.

format : string

The extending format for the previously mentioned type. See Data Type Formats for further details.

collectionFormat : string

Determines the format of the array if type array is used.

Possible values are:
- csv: comma separated values foo,bar.
- ssv: space separated values foo bar.
- tsv: tab separated values foo\tbar.
- pipes: pipe separated values foo|bar.
- multi: corresponds to multiple parameter instances instead of multiple values for a single instance
foo=bar&foo=baz. This is valid only for parameters of type query or formData. Default
value is csv.

default

Sets a default value to the parameter. The type of the value depends on the defined type.

See: JSON schema validation

maximum : int|float

The maximum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMaximum : bool|int|float

A boolean indicating whether the maximum value is excluded from the set of valid values.

When set to true, the maximum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

minimum : int|float

The minimum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMinimum : bool|int|float

A boolean indicating whether the minimum value is excluded from the set of valid values.

When set to true, the minimum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

maxLength : int

The maximum length of a string property.

A string instance is valid against this property if its length is less than, or equal to, the value of this
attribute.

See: JSON schema validation

minLength : int

The minimum length of a string property.

A string instance is valid against this property if its length is greater than, or equal to, the value of this
attribute.

See: JSON schema validation

pattern : string

A string instance is considered valid if the regular expression matches the instance successfully.

maxItems : int

The maximum number of items allowed in an array property.

An array instance is valid against this property if its number of items is less than, or equal to, the value of
this attribute.

See: JSON schema validation

minItems : int

The minimum number of items allowed in an array property.

An array instance is valid against this property if its number of items is greater than, or equal to, the value
of this attribute.

See: JSON schema validation

uniqueItems : bool

A boolean value indicating whether all items in an array property must be unique.

If this attribute is set to true, then all items in the array must be unique.

See: JSON schema validation

enum : array<string|int|float|bool|\UnitEnum>|class-string

A collection of allowable values for a property.

A property instance is valid against this attribute if its value is one of the values specified in this
collection.

See: JSON schema validation

multipleOf : int|float

A numeric instance is valid against "multipleOf" if the result of the division of the instance by this
property's value is an integer.

readOnly : bool

Declares the property as "read only".

Relevant only for Schema "properties" definitions.

This means that it may be sent as part of a response but should not be sent as part of the request.
If the property is marked as readOnly being true and is in the required list, the required will take effect on
the response only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

writeOnly : bool

Declares the property as "write only".

Relevant only for Schema "properties" definitions.
Therefore, it may be sent as part of a request but should not be sent as part of the response.
If the property is marked as writeOnly being true and is in the required list, the required will take effect on
the request only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

example

A free-form property to include an example of an instance for this schema.

To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
contain the example with escaping where necessary.

nullable : bool

Allows sending a null value for the defined schema.
Default value is false.

This must not be used when using OpenApi version 3.1,
instead make the "type" property an array and add "null" as a possible type.

deprecated : bool

Specifies that a schema is deprecated and should be transitioned out of usage.
Default value is false.

allOf : array<Schema|\OpenApi\Attributes\Schema>

An instance validates successfully against this property if it validates successfully against all schemas
defined by this property's value.

anyOf : array<Schema|\OpenApi\Attributes\Schema>

An instance validates successfully against this property if it validates successfully against at least one
schema defined by this property's value.

oneOf : array<Schema|\OpenApi\Attributes\Schema>

An instance validates successfully against this property if it validates successfully against exactly one schema
defined by this property's value.

not

http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.29.

additionalItems

http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.10.

contains

http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.14.

patternProperties

http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.19.

dependencies

http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.21.

propertyNames

http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.22.

const

http://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.1.3.

Reference

SecurityScheme

Allowed in

Components

Nested elements

Flow, Attachable

Properties

ref : string|class-string|object

The relative or absolute path to a security scheme.

See: Using refs

securityScheme : string

The key into OpenApi->security array.

type : string|non-empty-array<string>

The type of the security scheme.

description : string

A short description for security scheme.

name : string

The name of the header or query parameter to be used.

in : string

Required The location of the API key.

bearerFormat : string

A hint to the client to identify how the bearer token is formatted.

Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.

scheme : string

The name of the HTTP Authorization scheme.

See: RFC7235

openIdConnectUrl : string

OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL.

Reference

Server

An object representing a server.

Allowed in

OpenApi, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace, Link

Nested elements

ServerVariable, Attachable

Properties

url : string

An URL to the target host.

This URL supports Server Variables and may be relative,
to indicate that the host location is relative to the location where the OpenAPI document is being served.
Variable substitutions will be made when a variable is named in {brackets}.

description : string

An optional string describing the host designated by the URL.

CommonMark syntax may be used for rich text representation.

Reference

ServerVariable

An object representing a server variable for server URL template substitution.

Allowed in

Server

Nested elements

Attachable

Properties

serverVariable : string

The key into Server->variables array.

enum : array<string|int|float|bool|\UnitEnum>|class-string

An enumeration of values to be used if the substitution options are from a limited set.

default : string

The default value to use for substitution, and to send, if an alternate value is not supplied.

Unlike the Schema Object's default, this value must be provided by the consumer.

variables : array

A map between a variable name and its value.

The value is used for substitution in the server's URL template.

description : string

An optional description for the server variable.

CommonMark syntax MAY be used for rich text representation.

Reference

Tag

Allowed in

OpenApi

Nested elements

ExternalDocumentation, Attachable

Properties

name : string

The name of the tag.

description : string

A short description for the tag. GFM syntax can be used for rich text representation.

Reference

Trace

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Properties

method

No details available.

Webhook

Acts like a PathItem with the main difference being that it requires webhook instead of path.

Allowed in

OpenApi

Nested elements

Get, Post, Put, Delete, Patch, Trace, Head, Options, Parameter, PathParameter, Server, Attachable

Properties

webhook : string

Key for the webhooks map.

Xml

Allowed in

AdditionalProperties, Schema, Property, Schema, Items, XmlContent

Nested elements

Attachable

Properties

name : string

Replaces the name of the element/attribute used for the described schema property.

When defined within the Items Object (items), it will affect the name of the individual XML elements within the list.
When defined alongside type being array (outside the items), it will affect the wrapping element
and only if wrapped is true.

If wrapped is false, it will be ignored.

namespace : string

The URL of the namespace definition. Value SHOULD be in the form of a URL.

prefix : string

The prefix to be used for the name.

attribute : bool

Declares whether the property definition translates to an attribute instead of an element.

Default value is false.

wrapped : bool

MAY be used only for an array definition.

Signifies whether the array is wrapped (for example <books><book/><book/></books>)
or unwrapped (<book/><book/>).

Default value is false. The definition takes effect only when defined alongside type being array (outside the items).

Reference

XmlContent

Shorthand for a xml response.

Use as @OA\Schema inside a Response and MediaType->'application/xml' will be generated.

Nested elements

Discriminator, Items, Property, ExternalDocumentation, Xml, AdditionalProperties, Examples, Attachable

+ + + + + \ No newline at end of file diff --git a/reference/attributes.html b/reference/attributes.html new file mode 100644 index 000000000..cf178aca7 --- /dev/null +++ b/reference/attributes.html @@ -0,0 +1,21 @@ + + + + + + Attributes | Swagger-PHP + + + + + + + + + +
Swagger-PHP

Attributes

This page is generated automatically from the swagger-php sources.

For improvements head over to GitHub and create a PR 😉

In addition to this page, there are also a number of examples which might help you out.

AdditionalProperties

Allowed in

Schema, Property, Items, JsonContent, XmlContent, AdditionalProperties

Nested elements

Discriminator, Items, Property, ExternalDocumentation, Xml, AdditionalProperties, Attachable

Parameters

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : string|null

The key into Components->schemas array.

title : string|null

Can be used to decorate a user interface with information about the data produced by this user interface.

Preferably short; use description for more details.

description : string|null

A description will provide explanation about the purpose of the instance described by this schema.

maxProperties : int|null

The maximum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is less than, or equal to, the
value of this attribute.

minProperties : int|null

The minimum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is greater than, or equal to, the
value of this attribute.

required : string[]

An object instance is valid against this property if its property set contains all elements in this property's
array value.

properties : Property[]

A collection of properties to define for an object.

Each property is represented as an instance of the Property class.

type : string|non-empty-array<string>|null

The type of the schema/property.

OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".

Since OpenApi v3.1 an array of types may be used.

format : string|null

The extending format for the previously mentioned type. See Data Type Formats for further details.

items : OpenApi\Attributes\Items|null

Required if type is "array". Describes the type of items in the array.

collectionFormat : string|null

Determines the format of the array if type array is used.

Possible values are:
- csv: comma separated values foo,bar.
- ssv: space separated values foo bar.
- tsv: tab separated values foo\tbar.
- pipes: pipe separated values foo|bar.
- multi: corresponds to multiple parameter instances instead of multiple values for a single instance
foo=bar&foo=baz. This is valid only for parameters of type query or formData. Default
value is csv.

default : mixed|null

Sets a default value to the parameter. The type of the value depends on the defined type.

See: JSON schema validation

maximum : int|float

The maximum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMaximum : int|float|bool|null

A boolean indicating whether the maximum value is excluded from the set of valid values.

When set to true, the maximum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

minimum : int|float

The minimum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMinimum : int|float|bool|null

A boolean indicating whether the minimum value is excluded from the set of valid values.

When set to true, the minimum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

maxLength : int|null

The maximum length of a string property.

A string instance is valid against this property if its length is less than, or equal to, the value of this
attribute.

See: JSON schema validation

minLength : int|null

The minimum length of a string property.

A string instance is valid against this property if its length is greater than, or equal to, the value of this
attribute.

See: JSON schema validation

maxItems : int|null

The maximum number of items allowed in an array property.

An array instance is valid against this property if its number of items is less than, or equal to, the value of
this attribute.

See: JSON schema validation

minItems : int|null

The minimum number of items allowed in an array property.

An array instance is valid against this property if its number of items is greater than, or equal to, the value
of this attribute.

See: JSON schema validation

uniqueItems : bool|null

A boolean value indicating whether all items in an array property must be unique.

If this attribute is set to true, then all items in the array must be unique.

See: JSON schema validation

pattern : string|null

A string instance is considered valid if the regular expression matches the instance successfully.

enum : array<string|int|float|bool|\UnitEnum|null>|class-string|null

A collection of allowable values for a property.

A property instance is valid against this attribute if its value is one of the values specified in this
collection.

See: JSON schema validation

discriminator : OpenApi\Attributes\Discriminator|null

Adds support for polymorphism.

The discriminator is an object name that is used to differentiate between other schemas which may satisfy the
payload description. See Composition and Inheritance for more details.

readOnly : bool|null

Declares the property as "read only".

Relevant only for Schema "properties" definitions.

This means that it may be sent as part of a response but should not be sent as part of the request.
If the property is marked as readOnly being true and is in the required list, the required will take effect on
the response only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

writeOnly : bool|null

Declares the property as "write only".

Relevant only for Schema "properties" definitions.
Therefore, it may be sent as part of a request but should not be sent as part of the response.
If the property is marked as writeOnly being true and is in the required list, the required will take effect on
the request only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

xml : OpenApi\Attributes\Xml|null

This may be used only on properties schemas.

It has no effect on root schemas.
Adds additional metadata to describe the XML representation of this property.

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this schema.

example : mixed|null

A free-form property to include an example of an instance for this schema.

To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
contain the example with escaping where necessary.

nullable : bool|null

Allows sending a null value for the defined schema.
Default value is false.

This must not be used when using OpenApi version 3.1,
instead make the "type" property an array and add "null" as a possible type.

deprecated : bool|null

Specifies that a schema is deprecated and should be transitioned out of usage.
Default value is false.

allOf : array<Schema|\OpenApi\Annotations\Schema>

An instance validates successfully against this property if it validates successfully against all schemas
defined by this property's value.

anyOf : array<Schema|\OpenApi\Annotations\Schema>

An instance validates successfully against this property if it validates successfully against at least one
schema defined by this property's value.

oneOf : array<Schema|\OpenApi\Annotations\Schema>

An instance validates successfully against this property if it validates successfully against exactly one schema
defined by this property's value.

additionalProperties : OpenApi\Attributes\AdditionalProperties|bool|null

http://json-schema.org/latest/json-schema-validation.html#anchor64.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Attachable

Allowed in

AdditionalProperties, Components, Contact, Delete, Discriminator, Examples, ExternalDocumentation, Flow, Get, Head, Header, Info, Items, JsonContent, License, Link, MediaType, OpenApi, Operation, Options, Parameter, Patch, PathItem, PathParameter, Post, Property, Put, RequestBody, Response, Schema, SecurityScheme, Server, ServerVariable, Tag, Trace, Webhook, Xml, XmlContent

Parameters

properties : array

No details available.

Components

Allowed in

OpenApi

Nested elements

Response, Parameter, PathParameter, RequestBody, Examples, Header, SecurityScheme, Link, Schema, Attachable

Parameters

schemas : array<Schema|\OpenApi\Annotations\Schema>|null

Reusable Schemas.

responses : Response[]|null

Reusable Responses.

parameters : Parameter[]|null

Reusable Parameters.

requestBodies : RequestBody[]|null

Reusable Request Bodies.

examples : array<Examples>|null

Reusable Examples.

headers : Header[]|null

Reusable Headers.

securitySchemes : SecurityScheme[]|null

Reusable Security Schemes.

links : Link[]|null

Reusable Links.

callbacks : array|null

Reusable Callbacks.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Contact

Allowed in

Info

Nested elements

Attachable

Parameters

name : string|null

The identifying name of the contact person/organization.

url : string|null

The URL pointing to the contact information.

email : string|null

The email address of the contact person/organization.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

CookieParameter

Allowed in

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements

Schema, Examples, Attachable

Parameters

parameter : string|null

The key into Components::parameters or PathItem::parameters array.

name : string|null

The (case-sensitive) name of the parameter.

If in is "path", the name field must correspond to the associated path segment from the path field in the Paths Object.

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition shall be ignored.
For all other cases, the name corresponds to the parameter name used by the in property.

description : string|null

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

in : string|null

This takes 'cookie' as the default location.

required : bool|null

Determines whether this parameter is mandatory.

If the parameter location is "path", this property is required and its value must be true.
Otherwise, the property may be included and its default value is false.

deprecated : bool|null

Specifies that a parameter is deprecated and should be transitioned out of usage.

allowEmptyValue : bool|null

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue shall be ignored.

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : OpenApi\Attributes\Schema|null

The schema defining the type used for the parameter.

example : mixed|null

Example of the media type.

The example should match the specified schema and encoding properties if present.
The example object is mutually exclusive of the examples object.
Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema.
To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

examples : array<Examples>

Examples of the parameter.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

content : array<MediaType>|JsonContent|XmlContent|Attachable|null

A map containing the representations for the parameter.

The key is the media type and the value describes it.
The map must only contain one entry.

style : string|null

Describes how the parameter value will be serialized depending on the type of the parameter value.

Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

explode : bool|null

When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.

For other types of parameters this property has no effect.

When style is form, the default value is true.
For all other styles, the default value is false.

allowReserved : bool|null

Determines whether the parameter value should allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.

This property only applies to parameters with an in value of query.

The default value is false.

spaceDelimited : array|null

Space separated array values.

This option replaces collectionFormat equal to ssv from OpenAPI 2.0.

pipeDelimited : array|null

Pipe separated array values.

This option replaces collectionFormat equal to pipes from OpenAPI 2.0.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Delete

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters

path : string|null

Key in the OpenApi "Paths Object" for this operation.

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

summary : string|null

A short summary of what the operation does.

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

requestBody : OpenApi\Attributes\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

responses : Response[]

The list of possible responses as they are returned from executing this operation.

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this operation.

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Discriminator

Allowed in

Schema, Property, AdditionalProperties, Items, JsonContent, XmlContent

Nested elements

Attachable

Parameters

propertyName : string|null

The name of the property in the payload that will hold the discriminator value.

mapping : string[]|null

An object to hold mappings between payload values and schema names or references.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Examples

Allowed in

Components, Schema, Parameter, PathParameter, MediaType, JsonContent, XmlContent

Nested elements

Attachable

Parameters

example : string|null

The key into `#/components/examples`.

summary : string|null

Short description for the example.

description : string|null

Embedded literal example.

The value field and externalValue field are mutually exclusive.

To represent examples of media types that cannot naturally be represented
in JSON or YAML, use a string value to contain the example, escaping where necessary.

value : array|string|int|null

Embedded literal example.

The value field and externalValue field are mutually exclusive.

To represent examples of media types that cannot naturally be represented
in JSON or YAML, use a string value to contain the example, escaping where necessary.

externalValue : string|null

An URL that points to the literal example.

This provides the capability to reference examples that cannot easily be included
in JSON or YAML documents.

The value field and externalValue field are mutually exclusive.

ref : string|class-string|object|null

The relative or absolute path to an example.

See: Using refs

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

ExternalDocumentation

Allowed in

OpenApi, Tag, Schema, AdditionalProperties, Property, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace, Items, JsonContent, XmlContent

Nested elements

Attachable

Parameters

description : string|null

A short description of the target documentation. GFM syntax can be used for rich text representation.

url : string|null

The URL for the target documentation.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Flow

Allowed in

SecurityScheme

Nested elements

Attachable

Parameters

authorizationUrl : string|null

The authorization url to be used for this flow.

This must be in the form of an url.

tokenUrl : string|null

The token URL to be used for this flow.

This must be in the form of an url.

refreshUrl : string|null

The URL to be used for obtaining refresh tokens.

This must be in the form of an url.

flow : string|null

Flow name.

One of ['implicit', 'password', 'authorizationCode', 'clientCredentials'].

scopes : array|null

The available scopes for the OAuth2 security scheme.

A map between the scope name and a short description for it.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Get

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters

path : string|null

Key in the OpenApi "Paths Object" for this operation.

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

summary : string|null

A short summary of what the operation does.

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

requestBody : OpenApi\Attributes\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

responses : Response[]

The list of possible responses as they are returned from executing this operation.

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this operation.

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters

path : string|null

Key in the OpenApi "Paths Object" for this operation.

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

summary : string|null

A short summary of what the operation does.

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

requestBody : OpenApi\Attributes\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

responses : Response[]

The list of possible responses as they are returned from executing this operation.

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this operation.

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Allowed in

Components, Response

Nested elements

Schema, Attachable

Parameters

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

header : string|null

No details available.

description : string|null

A brief description of the parameter.

This could contain examples of use.
CommonMark syntax MAY be used for rich text representation.

required : bool|null

No details available.

schema : OpenApi\Attributes\Schema|null

Schema object.

deprecated : bool|null

Specifies that a parameter is deprecated and SHOULD be transitioned out of usage.

allowEmptyValue : bool|null

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

HeaderParameter

Allowed in

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements

Schema, Examples, Attachable

Parameters

parameter : string|null

The key into Components::parameters or PathItem::parameters array.

name : string|null

The (case-sensitive) name of the parameter.

If in is "path", the name field must correspond to the associated path segment from the path field in the Paths Object.

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition shall be ignored.
For all other cases, the name corresponds to the parameter name used by the in property.

description : string|null

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

in : string|null

This takes 'header' as the default location.

required : bool|null

Determines whether this parameter is mandatory.

If the parameter location is "path", this property is required and its value must be true.
Otherwise, the property may be included and its default value is false.

deprecated : bool|null

Specifies that a parameter is deprecated and should be transitioned out of usage.

allowEmptyValue : bool|null

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue shall be ignored.

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : OpenApi\Attributes\Schema|null

The schema defining the type used for the parameter.

example : mixed|null

Example of the media type.

The example should match the specified schema and encoding properties if present.
The example object is mutually exclusive of the examples object.
Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema.
To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

examples : array<Examples>

Examples of the parameter.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

content : array<MediaType>|JsonContent|XmlContent|Attachable|null

A map containing the representations for the parameter.

The key is the media type and the value describes it.
The map must only contain one entry.

style : string|null

Describes how the parameter value will be serialized depending on the type of the parameter value.

Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

explode : bool|null

When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.

For other types of parameters this property has no effect.

When style is form, the default value is true.
For all other styles, the default value is false.

allowReserved : bool|null

Determines whether the parameter value should allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.

This property only applies to parameters with an in value of query.

The default value is false.

spaceDelimited : array|null

Space separated array values.

This option replaces collectionFormat equal to ssv from OpenAPI 2.0.

pipeDelimited : array|null

Pipe separated array values.

This option replaces collectionFormat equal to pipes from OpenAPI 2.0.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Info

Allowed in

OpenApi

Nested elements

Contact, License, Attachable

Parameters

version : string|null

The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).

description : string|null

A short description of the application.

CommonMark syntax may be used for rich text representation.

title : string|null

The title of the application.

termsOfService : string|null

An URL to the Terms of Service for the API.

Must be in the format of an url.

contact : OpenApi\Attributes\Contact|null

The contact information for the exposed API.

license : OpenApi\Attributes\License|null

The license information for the exposed API.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Items

Allowed in

Property, AdditionalProperties, Schema, JsonContent, XmlContent, Items

Nested elements

Discriminator, Items, Property, ExternalDocumentation, Xml, AdditionalProperties, Attachable

Parameters

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : string|null

The key into Components->schemas array.

title : string|null

Can be used to decorate a user interface with information about the data produced by this user interface.

Preferably short; use description for more details.

description : string|null

A description will provide explanation about the purpose of the instance described by this schema.

maxProperties : int|null

The maximum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is less than, or equal to, the
value of this attribute.

minProperties : int|null

The minimum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is greater than, or equal to, the
value of this attribute.

required : string[]

An object instance is valid against this property if its property set contains all elements in this property's
array value.

properties : Property[]

A collection of properties to define for an object.

Each property is represented as an instance of the Property class.

type : string|non-empty-array<string>|null

The type of the schema/property.

OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".

Since OpenApi v3.1 an array of types may be used.

format : string|null

The extending format for the previously mentioned type. See Data Type Formats for further details.

items : OpenApi\Attributes\Items|null

Required if type is "array". Describes the type of items in the array.

collectionFormat : string|null

Determines the format of the array if type array is used.

Possible values are:
- csv: comma separated values foo,bar.
- ssv: space separated values foo bar.
- tsv: tab separated values foo\tbar.
- pipes: pipe separated values foo|bar.
- multi: corresponds to multiple parameter instances instead of multiple values for a single instance
foo=bar&foo=baz. This is valid only for parameters of type query or formData. Default
value is csv.

default : mixed|null

Sets a default value to the parameter. The type of the value depends on the defined type.

See: JSON schema validation

maximum : int|float

The maximum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMaximum : int|float|bool|null

A boolean indicating whether the maximum value is excluded from the set of valid values.

When set to true, the maximum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

minimum : int|float

The minimum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMinimum : int|float|bool|null

A boolean indicating whether the minimum value is excluded from the set of valid values.

When set to true, the minimum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

maxLength : int|null

The maximum length of a string property.

A string instance is valid against this property if its length is less than, or equal to, the value of this
attribute.

See: JSON schema validation

minLength : int|null

The minimum length of a string property.

A string instance is valid against this property if its length is greater than, or equal to, the value of this
attribute.

See: JSON schema validation

maxItems : int|null

The maximum number of items allowed in an array property.

An array instance is valid against this property if its number of items is less than, or equal to, the value of
this attribute.

See: JSON schema validation

minItems : int|null

The minimum number of items allowed in an array property.

An array instance is valid against this property if its number of items is greater than, or equal to, the value
of this attribute.

See: JSON schema validation

uniqueItems : bool|null

A boolean value indicating whether all items in an array property must be unique.

If this attribute is set to true, then all items in the array must be unique.

See: JSON schema validation

pattern : string|null

A string instance is considered valid if the regular expression matches the instance successfully.

enum : array<string|int|float|bool|\UnitEnum|null>|class-string|null

A collection of allowable values for a property.

A property instance is valid against this attribute if its value is one of the values specified in this
collection.

See: JSON schema validation

discriminator : OpenApi\Attributes\Discriminator|null

Adds support for polymorphism.

The discriminator is an object name that is used to differentiate between other schemas which may satisfy the
payload description. See Composition and Inheritance for more details.

readOnly : bool|null

Declares the property as "read only".

Relevant only for Schema "properties" definitions.

This means that it may be sent as part of a response but should not be sent as part of the request.
If the property is marked as readOnly being true and is in the required list, the required will take effect on
the response only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

writeOnly : bool|null

Declares the property as "write only".

Relevant only for Schema "properties" definitions.
Therefore, it may be sent as part of a request but should not be sent as part of the response.
If the property is marked as writeOnly being true and is in the required list, the required will take effect on
the request only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

xml : OpenApi\Attributes\Xml|null

This may be used only on properties schemas.

It has no effect on root schemas.
Adds additional metadata to describe the XML representation of this property.

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this schema.

example : mixed|null

A free-form property to include an example of an instance for this schema.

To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
contain the example with escaping where necessary.

nullable : bool|null

Allows sending a null value for the defined schema.
Default value is false.

This must not be used when using OpenApi version 3.1,
instead make the "type" property an array and add "null" as a possible type.

deprecated : bool|null

Specifies that a schema is deprecated and should be transitioned out of usage.
Default value is false.

allOf : array<Schema|\OpenApi\Annotations\Schema>

An instance validates successfully against this property if it validates successfully against all schemas
defined by this property's value.

anyOf : array<Schema|\OpenApi\Annotations\Schema>

An instance validates successfully against this property if it validates successfully against at least one
schema defined by this property's value.

oneOf : array<Schema|\OpenApi\Annotations\Schema>

An instance validates successfully against this property if it validates successfully against exactly one schema
defined by this property's value.

additionalProperties : OpenApi\Attributes\AdditionalProperties|bool|null

http://json-schema.org/latest/json-schema-validation.html#anchor64.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

JsonContent

Nested elements

Discriminator, Items, Property, ExternalDocumentation, AdditionalProperties, Examples, Attachable

Parameters

examples : array<Examples>

Examples of the schema.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : string|null

The key into Components->schemas array.

title : string|null

Can be used to decorate a user interface with information about the data produced by this user interface.

Preferably short; use description for more details.

description : string|null

A description will provide explanation about the purpose of the instance described by this schema.

maxProperties : int|null

The maximum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is less than, or equal to, the
value of this attribute.

minProperties : int|null

The minimum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is greater than, or equal to, the
value of this attribute.

required : string[]

An object instance is valid against this property if its property set contains all elements in this property's
array value.

properties : Property[]

A collection of properties to define for an object.

Each property is represented as an instance of the Property class.

type : string|non-empty-array<string>|null

The type of the schema/property.

OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".

Since OpenApi v3.1 an array of types may be used.

format : string|null

The extending format for the previously mentioned type. See Data Type Formats for further details.

items : OpenApi\Attributes\Items|null

Required if type is "array". Describes the type of items in the array.

collectionFormat : string|null

Determines the format of the array if type array is used.

Possible values are:
- csv: comma separated values foo,bar.
- ssv: space separated values foo bar.
- tsv: tab separated values foo\tbar.
- pipes: pipe separated values foo|bar.
- multi: corresponds to multiple parameter instances instead of multiple values for a single instance
foo=bar&foo=baz. This is valid only for parameters of type query or formData. Default
value is csv.

default : mixed|null

Sets a default value to the parameter. The type of the value depends on the defined type.

See: JSON schema validation

maximum : int|float

The maximum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMaximum : int|float|bool|null

A boolean indicating whether the maximum value is excluded from the set of valid values.

When set to true, the maximum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

minimum : int|float

The minimum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMinimum : int|float|bool|null

A boolean indicating whether the minimum value is excluded from the set of valid values.

When set to true, the minimum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

maxLength : int|null

The maximum length of a string property.

A string instance is valid against this property if its length is less than, or equal to, the value of this
attribute.

See: JSON schema validation

minLength : int|null

The minimum length of a string property.

A string instance is valid against this property if its length is greater than, or equal to, the value of this
attribute.

See: JSON schema validation

maxItems : int|null

The maximum number of items allowed in an array property.

An array instance is valid against this property if its number of items is less than, or equal to, the value of
this attribute.

See: JSON schema validation

minItems : int|null

The minimum number of items allowed in an array property.

An array instance is valid against this property if its number of items is greater than, or equal to, the value
of this attribute.

See: JSON schema validation

uniqueItems : bool|null

A boolean value indicating whether all items in an array property must be unique.

If this attribute is set to true, then all items in the array must be unique.

See: JSON schema validation

pattern : string|null

A string instance is considered valid if the regular expression matches the instance successfully.

enum : array<string|int|float|bool|\UnitEnum|null>|class-string|null

A collection of allowable values for a property.

A property instance is valid against this attribute if its value is one of the values specified in this
collection.

See: JSON schema validation

discriminator : OpenApi\Attributes\Discriminator|null

Adds support for polymorphism.

The discriminator is an object name that is used to differentiate between other schemas which may satisfy the
payload description. See Composition and Inheritance for more details.

readOnly : bool|null

Declares the property as "read only".

Relevant only for Schema "properties" definitions.

This means that it may be sent as part of a response but should not be sent as part of the request.
If the property is marked as readOnly being true and is in the required list, the required will take effect on
the response only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

writeOnly : bool|null

Declares the property as "write only".

Relevant only for Schema "properties" definitions.
Therefore, it may be sent as part of a request but should not be sent as part of the response.
If the property is marked as writeOnly being true and is in the required list, the required will take effect on
the request only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

xml : OpenApi\Attributes\Xml|null

This may be used only on properties schemas.

It has no effect on root schemas.
Adds additional metadata to describe the XML representation of this property.

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this schema.

example : mixed|null

A free-form property to include an example of an instance for this schema.

To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
contain the example with escaping where necessary.

nullable : bool|null

Allows sending a null value for the defined schema.
Default value is false.

This must not be used when using OpenApi version 3.1,
instead make the "type" property an array and add "null" as a possible type.

deprecated : bool|null

Specifies that a schema is deprecated and should be transitioned out of usage.
Default value is false.

allOf : array<Schema|\OpenApi\Annotations\Schema>

An instance validates successfully against this property if it validates successfully against all schemas
defined by this property's value.

anyOf : array<Schema|\OpenApi\Annotations\Schema>

An instance validates successfully against this property if it validates successfully against at least one
schema defined by this property's value.

oneOf : array<Schema|\OpenApi\Annotations\Schema>

An instance validates successfully against this property if it validates successfully against exactly one schema
defined by this property's value.

additionalProperties : OpenApi\Attributes\AdditionalProperties|bool|null

http://json-schema.org/latest/json-schema-validation.html#anchor64.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

License

Allowed in

Info

Nested elements

Attachable

Parameters

name : string|null

The license name used for the API.

identifier : string|null

An SPDX license expression for the API. The `identifier` field is mutually exclusive of the `url` field.

url : string|null

An URL to the license used for the API. This MUST be in the form of a URL.

The `url` field is mutually exclusive of the `identifier` field.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Allowed in

Components, Response

Nested elements

Server, Attachable

Parameters

link : string|null

The key into MediaType->links array.

operationRef : string|null

A relative or absolute reference to an OA operation.

This field is mutually exclusive of the operationId field, and must point to an Operation object.

Relative values may be used to locate an existing Operation object in the OpenAPI definition.

ref : string|class-string|object|null

No details available.

See: Using refs

operationId : string|null

The name of an existing, resolvable OA operation, as defined with a unique operationId.

This field is mutually exclusive of the operationRef field.

parameters : array<string,mixed>

A map representing parameters to pass to an operation as specified with operationId or identified via
operationRef.

The key is the parameter name to be used, whereas the value can be a constant or an expression to
be evaluated and passed to the linked operation.
The parameter name can be qualified using the parameter location [{in}.]{name} for operations
that use the same parameter name in different locations (e.g. path.id).

requestBody : mixed|null

A literal value or {expression} to use as a request body when calling the target operation.

description : string|null

A description of the link.

CommonMark syntax may be used for rich text representation.

server : OpenApi\Attributes\Server|null

A server object to be used by the target operation.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

MediaType

Allowed in

Response, RequestBody

Nested elements

Schema, Examples, Attachable

Parameters

mediaType : string|null

The key into Operation->content array.

schema : OpenApi\Attributes\Schema|null

The schema defining the type used for the request body.

example : mixed|null

Example of the media type.

The example object should be in the correct format as specified by the media type.
The example object is mutually exclusive of the examples object.

Furthermore, if referencing a schema which contains an example,
the example value shall override the example provided by the schema.

examples : array<Examples>

Examples of the media type.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

encoding : array<string,mixed>

A map between a property name and its encoding information.

The key, being the property name, must exist in the schema as a property.

The encoding object shall only apply to requestBody objects when the media type is multipart or
application/x-www-form-urlencoded.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

OpenApi

Nested elements

Info, Server, PathItem, Components, Tag, ExternalDocumentation, Webhook, Attachable

Parameters

openapi : string

The semantic version number of the OpenAPI Specification version that the OpenAPI document uses.

The openapi field should be used by tooling specifications and clients to interpret the OpenAPI document.

A version specified via `Generator::setVersion()` will overwrite this value.

This is not related to the API info::version string.

info : OpenApi\Attributes\Info|null

Provides metadata about the API. The metadata may be used by tooling as required.

servers : Server[]|null

An array of @Server objects, which provide connectivity information to a target server.

If not provided, or is an empty array, the default value would be a Server Object with an url value of /.

security : array|null

A declaration of which security mechanisms can be used across the API.

The list of values includes alternative security requirement objects that can be used.
Only one of the security requirement objects need to be satisfied to authorize a request.
Individual operations can override this definition.
To make security optional, an empty security requirement `({})` can be included in the array.

tags : Tag[]|null

A list of tags used by the specification with additional metadata.

The order of the tags can be used to reflect on their order by the parsing tools.
Not all tags that are used by the Operation Object must be declared.
The tags that are not declared may be organized randomly or based on the tools' logic.
Each tag name in the list must be unique.

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation.

paths : PathItem[]|null

The available paths and operations for the API.

components : OpenApi\Attributes\Components|null

An element to hold various components for the specification.

webhooks : Webhook[]|null

The available webhooks for the API.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Options

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters

path : string|null

Key in the OpenApi "Paths Object" for this operation.

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

summary : string|null

A short summary of what the operation does.

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

requestBody : OpenApi\Attributes\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

responses : Response[]

The list of possible responses as they are returned from executing this operation.

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this operation.

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Parameter

Allowed in

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements

Schema, Examples, Attachable

Parameters

parameter : string|null

The key into Components::parameters or PathItem::parameters array.

name : string|null

The (case-sensitive) name of the parameter.

If in is "path", the name field must correspond to the associated path segment from the path field in the Paths Object.

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition shall be ignored.
For all other cases, the name corresponds to the parameter name used by the in property.

description : string|null

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

in : string|null

The location of the parameter.

Possible values are "query", "header", "path" or "cookie".

required : bool|null

Determines whether this parameter is mandatory.

If the parameter location is "path", this property is required and its value must be true.
Otherwise, the property may be included and its default value is false.

deprecated : bool|null

Specifies that a parameter is deprecated and should be transitioned out of usage.

allowEmptyValue : bool|null

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue shall be ignored.

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : OpenApi\Attributes\Schema|null

The schema defining the type used for the parameter.

example : mixed|null

Example of the media type.

The example should match the specified schema and encoding properties if present.
The example object is mutually exclusive of the examples object.
Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema.
To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

examples : array<Examples>

Examples of the parameter.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

content : array<MediaType>|JsonContent|XmlContent|Attachable|null

A map containing the representations for the parameter.

The key is the media type and the value describes it.
The map must only contain one entry.

style : string|null

Describes how the parameter value will be serialized depending on the type of the parameter value.

Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

explode : bool|null

When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.

For other types of parameters this property has no effect.

When style is form, the default value is true.
For all other styles, the default value is false.

allowReserved : bool|null

Determines whether the parameter value should allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.

This property only applies to parameters with an in value of query.

The default value is false.

spaceDelimited : array|null

Space separated array values.

This option replaces collectionFormat equal to ssv from OpenAPI 2.0.

pipeDelimited : array|null

Pipe separated array values.

This option replaces collectionFormat equal to pipes from OpenAPI 2.0.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Patch

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters

path : string|null

Key in the OpenApi "Paths Object" for this operation.

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

summary : string|null

A short summary of what the operation does.

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

requestBody : OpenApi\Attributes\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

responses : Response[]

The list of possible responses as they are returned from executing this operation.

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this operation.

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

PathItem

Allowed in

OpenApi

Nested elements

Get, Post, Put, Delete, Patch, Trace, Head, Options, Parameter, PathParameter, Server, Attachable

Parameters

path : string|null

Key for the Path Object (OpenApi->paths array).

ref : string|class-string|object|null

No details available.

See: Using refs

summary : string|null

An optional, string summary, intended to apply to all operations in this path.

description : string|null

An optional, string description, intended to apply to all operations in this path.

get : OpenApi\Attributes\Get|null

A definition of a GET operation on this path.

put : OpenApi\Attributes\Put|null

A definition of a PUT operation on this path.

post : OpenApi\Attributes\Post|null

A definition of a POST operation on this path.

delete : OpenApi\Attributes\Delete|null

A definition of a DELETE operation on this path.

options : OpenApi\Attributes\Options|null

A definition of a OPTIONS operation on this path.

head : OpenApi\Attributes\Head|null

A definition of a HEAD operation on this path.

patch : OpenApi\Attributes\Patch|null

A definition of a PATCH operation on this path.

trace : OpenApi\Attributes\Trace|null

A definition of a TRACE operation on this path.

servers : Server[]|null

An alternative server array to service all operations in this path.

parameters : Parameter[]|null

A list of parameters that are applicable for all the operations described under this path.

These parameters can be overridden at the operation level, but cannot be removed there.
The list must not include duplicated parameters.
A unique parameter is defined by a combination of a name and location.
The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's components/parameters.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

PathParameter

Allowed in

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements

Schema, Examples, Attachable

Parameters

parameter : string|null

The key into Components::parameters or PathItem::parameters array.

name : string|null

The (case-sensitive) name of the parameter.

If in is "path", the name field must correspond to the associated path segment from the path field in the Paths Object.

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition shall be ignored.
For all other cases, the name corresponds to the parameter name used by the in property.

description : string|null

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

in : string|null

This takes 'path' as the default location.

required : bool|null

No details available.

deprecated : bool|null

Specifies that a parameter is deprecated and should be transitioned out of usage.

allowEmptyValue : bool|null

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue shall be ignored.

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : OpenApi\Attributes\Schema|null

The schema defining the type used for the parameter.

example : mixed|null

Example of the media type.

The example should match the specified schema and encoding properties if present.
The example object is mutually exclusive of the examples object.
Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema.
To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

examples : array<Examples>

Examples of the parameter.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

content : array<MediaType>|JsonContent|XmlContent|Attachable|null

A map containing the representations for the parameter.

The key is the media type and the value describes it.
The map must only contain one entry.

style : string|null

Describes how the parameter value will be serialized depending on the type of the parameter value.

Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

explode : bool|null

When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.

For other types of parameters this property has no effect.

When style is form, the default value is true.
For all other styles, the default value is false.

allowReserved : bool|null

Determines whether the parameter value should allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.

This property only applies to parameters with an in value of query.

The default value is false.

spaceDelimited : array|null

Space separated array values.

This option replaces collectionFormat equal to ssv from OpenAPI 2.0.

pipeDelimited : array|null

Pipe separated array values.

This option replaces collectionFormat equal to pipes from OpenAPI 2.0.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Post

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters

path : string|null

Key in the OpenApi "Paths Object" for this operation.

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

summary : string|null

A short summary of what the operation does.

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

requestBody : OpenApi\Attributes\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

responses : Response[]

The list of possible responses as they are returned from executing this operation.

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this operation.

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Property

Allowed in

AdditionalProperties, Schema, JsonContent, XmlContent, Property, Items

Nested elements

Discriminator, Items, Property, ExternalDocumentation, Xml, AdditionalProperties, Attachable

Parameters

property : string|null

The key into Schema->properties array.

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : string|null

The key into Components->schemas array.

title : string|null

Can be used to decorate a user interface with information about the data produced by this user interface.

Preferably short; use description for more details.

description : string|null

A description will provide explanation about the purpose of the instance described by this schema.

maxProperties : int|null

The maximum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is less than, or equal to, the
value of this attribute.

minProperties : int|null

The minimum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is greater than, or equal to, the
value of this attribute.

required : string[]

An object instance is valid against this property if its property set contains all elements in this property's
array value.

properties : Property[]

A collection of properties to define for an object.

Each property is represented as an instance of the Property class.

type : string|non-empty-array<string>|null

The type of the schema/property.

OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".

Since OpenApi v3.1 an array of types may be used.

format : string|null

The extending format for the previously mentioned type. See Data Type Formats for further details.

items : OpenApi\Attributes\Items|null

Required if type is "array". Describes the type of items in the array.

collectionFormat : string|null

Determines the format of the array if type array is used.

Possible values are:
- csv: comma separated values foo,bar.
- ssv: space separated values foo bar.
- tsv: tab separated values foo\tbar.
- pipes: pipe separated values foo|bar.
- multi: corresponds to multiple parameter instances instead of multiple values for a single instance
foo=bar&foo=baz. This is valid only for parameters of type query or formData. Default
value is csv.

default : mixed|null

Sets a default value to the parameter. The type of the value depends on the defined type.

See: JSON schema validation

maximum : int|float

The maximum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMaximum : int|float|bool|null

A boolean indicating whether the maximum value is excluded from the set of valid values.

When set to true, the maximum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

minimum : int|float

The minimum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMinimum : int|float|bool|null

A boolean indicating whether the minimum value is excluded from the set of valid values.

When set to true, the minimum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

maxLength : int|null

The maximum length of a string property.

A string instance is valid against this property if its length is less than, or equal to, the value of this
attribute.

See: JSON schema validation

minLength : int|null

The minimum length of a string property.

A string instance is valid against this property if its length is greater than, or equal to, the value of this
attribute.

See: JSON schema validation

maxItems : int|null

The maximum number of items allowed in an array property.

An array instance is valid against this property if its number of items is less than, or equal to, the value of
this attribute.

See: JSON schema validation

minItems : int|null

The minimum number of items allowed in an array property.

An array instance is valid against this property if its number of items is greater than, or equal to, the value
of this attribute.

See: JSON schema validation

uniqueItems : bool|null

A boolean value indicating whether all items in an array property must be unique.

If this attribute is set to true, then all items in the array must be unique.

See: JSON schema validation

pattern : string|null

A string instance is considered valid if the regular expression matches the instance successfully.

enum : array<string|int|float|bool|\UnitEnum|null>|class-string|null

A collection of allowable values for a property.

A property instance is valid against this attribute if its value is one of the values specified in this
collection.

See: JSON schema validation

discriminator : OpenApi\Attributes\Discriminator|null

Adds support for polymorphism.

The discriminator is an object name that is used to differentiate between other schemas which may satisfy the
payload description. See Composition and Inheritance for more details.

readOnly : bool|null

Declares the property as "read only".

Relevant only for Schema "properties" definitions.

This means that it may be sent as part of a response but should not be sent as part of the request.
If the property is marked as readOnly being true and is in the required list, the required will take effect on
the response only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

writeOnly : bool|null

Declares the property as "write only".

Relevant only for Schema "properties" definitions.
Therefore, it may be sent as part of a request but should not be sent as part of the response.
If the property is marked as writeOnly being true and is in the required list, the required will take effect on
the request only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

xml : OpenApi\Attributes\Xml|null

This may be used only on properties schemas.

It has no effect on root schemas.
Adds additional metadata to describe the XML representation of this property.

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this schema.

example : mixed|null

A free-form property to include an example of an instance for this schema.

To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
contain the example with escaping where necessary.

nullable : bool|null

Allows sending a null value for the defined schema.
Default value is false.

This must not be used when using OpenApi version 3.1,
instead make the "type" property an array and add "null" as a possible type.

deprecated : bool|null

Specifies that a schema is deprecated and should be transitioned out of usage.
Default value is false.

allOf : array<Schema|\OpenApi\Annotations\Schema>

An instance validates successfully against this property if it validates successfully against all schemas
defined by this property's value.

anyOf : array<Schema|\OpenApi\Annotations\Schema>

An instance validates successfully against this property if it validates successfully against at least one
schema defined by this property's value.

oneOf : array<Schema|\OpenApi\Annotations\Schema>

An instance validates successfully against this property if it validates successfully against exactly one schema
defined by this property's value.

additionalProperties : OpenApi\Attributes\AdditionalProperties|bool|null

http://json-schema.org/latest/json-schema-validation.html#anchor64.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Put

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters

path : string|null

Key in the OpenApi "Paths Object" for this operation.

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

summary : string|null

A short summary of what the operation does.

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

requestBody : OpenApi\Attributes\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

responses : Response[]

The list of possible responses as they are returned from executing this operation.

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this operation.

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

QueryParameter

Allowed in

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements

Schema, Examples, Attachable

Parameters

parameter : string|null

The key into Components::parameters or PathItem::parameters array.

name : string|null

The (case-sensitive) name of the parameter.

If in is "path", the name field must correspond to the associated path segment from the path field in the Paths Object.

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition shall be ignored.
For all other cases, the name corresponds to the parameter name used by the in property.

description : string|null

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

in : string|null

This takes 'query' as the default location.

required : bool|null

Determines whether this parameter is mandatory.

If the parameter location is "path", this property is required and its value must be true.
Otherwise, the property may be included and its default value is false.

deprecated : bool|null

Specifies that a parameter is deprecated and should be transitioned out of usage.

allowEmptyValue : bool|null

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue shall be ignored.

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : OpenApi\Attributes\Schema|null

The schema defining the type used for the parameter.

example : mixed|null

Example of the media type.

The example should match the specified schema and encoding properties if present.
The example object is mutually exclusive of the examples object.
Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema.
To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

examples : array<Examples>

Examples of the parameter.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

content : array<MediaType>|JsonContent|XmlContent|Attachable|null

A map containing the representations for the parameter.

The key is the media type and the value describes it.
The map must only contain one entry.

style : string|null

Describes how the parameter value will be serialized depending on the type of the parameter value.

Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

explode : bool|null

When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.

For other types of parameters this property has no effect.

When style is form, the default value is true.
For all other styles, the default value is false.

allowReserved : bool|null

Determines whether the parameter value should allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.

This property only applies to parameters with an in value of query.

The default value is false.

spaceDelimited : array|null

Space separated array values.

This option replaces collectionFormat equal to ssv from OpenAPI 2.0.

pipeDelimited : array|null

Pipe separated array values.

This option replaces collectionFormat equal to pipes from OpenAPI 2.0.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

RequestBody

Allowed in

Components, Delete, Get, Head, Operation, Options, Patch, Post, Trace, Put

Nested elements

MediaType, Attachable

Parameters

ref : string|class-string|object|null

The relative or absolute path to a request body.

See: Using refs

request : string|null

The key into Components->requestBodies array.

description : string|null

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

required : bool|null

Determines whether this parameter is mandatory.

If the parameter location is "path", this property is required and its value must be true.
Otherwise, the property may be included and its default value is false.

content : array<MediaType|JsonContent|XmlContent>|MediaType|XmlContent|Attachable|null

The content of the request body.

The key is a media type or media type range and the value describes it. For requests that match multiple keys,
only the most specific key is applicable. e.g. text/plain overrides text/*.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Response

Allowed in

Components, Operation, Get, Post, Put, Patch, Delete, Head, Options, Trace

Nested elements

MediaType, Header, Link, Attachable

Parameters

ref : string|class-string|object|null

The relative or absolute path to a response.

See: Using refs

response : string|int|null

The key into Operations->responses array.

A HTTP status code or default.

description : string|null

A short description of the response.

CommonMark syntax may be used for rich text representation.

headers : Header[]

Maps a header name to its definition.

RFC7230 states header names are case insensitive.

If a response header is defined with the name "Content-Type", it shall be ignored.

See: RFC7230

content : MediaType|JsonContent|XmlContent|Attachable|array<MediaType|Attachable>

A map containing descriptions of potential response payloads.

The key is a media type or media type range and the value describes it.

For responses that match multiple keys, only the most specific key is applicable;
e.g. text/plain overrides text/*.

links : Link[]

A map of operations links that can be followed from the response.

The key of the map is a short name for the link, following the naming constraints of the names for Component
Objects.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Schema

Allowed in

Components, Parameter, PathParameter, MediaType, Header

Nested elements

Discriminator, Items, Property, ExternalDocumentation, Examples, Xml, AdditionalProperties, Attachable

Parameters

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : string|null

The key into Components->schemas array.

title : string|null

Can be used to decorate a user interface with information about the data produced by this user interface.

Preferably short; use description for more details.

description : string|null

A description will provide explanation about the purpose of the instance described by this schema.

maxProperties : int|null

The maximum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is less than, or equal to, the
value of this attribute.

minProperties : int|null

The minimum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is greater than, or equal to, the
value of this attribute.

required : string[]

An object instance is valid against this property if its property set contains all elements in this property's
array value.

properties : Property[]

A collection of properties to define for an object.

Each property is represented as an instance of the Property class.

type : string|non-empty-array<string>|null

The type of the schema/property.

OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".

Since OpenApi v3.1 an array of types may be used.

format : string|null

The extending format for the previously mentioned type. See Data Type Formats for further details.

items : OpenApi\Attributes\Items|null

Required if type is "array". Describes the type of items in the array.

collectionFormat : string|null

Determines the format of the array if type array is used.

Possible values are:
- csv: comma separated values foo,bar.
- ssv: space separated values foo bar.
- tsv: tab separated values foo\tbar.
- pipes: pipe separated values foo|bar.
- multi: corresponds to multiple parameter instances instead of multiple values for a single instance
foo=bar&foo=baz. This is valid only for parameters of type query or formData. Default
value is csv.

default : mixed|null

Sets a default value to the parameter. The type of the value depends on the defined type.

See: JSON schema validation

maximum : int|float

The maximum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMaximum : int|float|bool|null

A boolean indicating whether the maximum value is excluded from the set of valid values.

When set to true, the maximum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

minimum : int|float

The minimum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMinimum : int|float|bool|null

A boolean indicating whether the minimum value is excluded from the set of valid values.

When set to true, the minimum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

maxLength : int|null

The maximum length of a string property.

A string instance is valid against this property if its length is less than, or equal to, the value of this
attribute.

See: JSON schema validation

minLength : int|null

The minimum length of a string property.

A string instance is valid against this property if its length is greater than, or equal to, the value of this
attribute.

See: JSON schema validation

maxItems : int|null

The maximum number of items allowed in an array property.

An array instance is valid against this property if its number of items is less than, or equal to, the value of
this attribute.

See: JSON schema validation

minItems : int|null

The minimum number of items allowed in an array property.

An array instance is valid against this property if its number of items is greater than, or equal to, the value
of this attribute.

See: JSON schema validation

uniqueItems : bool|null

A boolean value indicating whether all items in an array property must be unique.

If this attribute is set to true, then all items in the array must be unique.

See: JSON schema validation

pattern : string|null

A string instance is considered valid if the regular expression matches the instance successfully.

enum : array<string|int|float|bool|\UnitEnum|null>|class-string|null

A collection of allowable values for a property.

A property instance is valid against this attribute if its value is one of the values specified in this
collection.

See: JSON schema validation

discriminator : OpenApi\Attributes\Discriminator|null

Adds support for polymorphism.

The discriminator is an object name that is used to differentiate between other schemas which may satisfy the
payload description. See Composition and Inheritance for more details.

readOnly : bool|null

Declares the property as "read only".

Relevant only for Schema "properties" definitions.

This means that it may be sent as part of a response but should not be sent as part of the request.
If the property is marked as readOnly being true and is in the required list, the required will take effect on
the response only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

writeOnly : bool|null

Declares the property as "write only".

Relevant only for Schema "properties" definitions.
Therefore, it may be sent as part of a request but should not be sent as part of the response.
If the property is marked as writeOnly being true and is in the required list, the required will take effect on
the request only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

xml : OpenApi\Attributes\Xml|null

This may be used only on properties schemas.

It has no effect on root schemas.
Adds additional metadata to describe the XML representation of this property.

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this schema.

example : mixed|null

A free-form property to include an example of an instance for this schema.

To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
contain the example with escaping where necessary.

examples : array<Examples>

Examples of the schema.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

nullable : bool|null

Allows sending a null value for the defined schema.
Default value is false.

This must not be used when using OpenApi version 3.1,
instead make the "type" property an array and add "null" as a possible type.

deprecated : bool|null

Specifies that a schema is deprecated and should be transitioned out of usage.
Default value is false.

allOf : array<Schema|\OpenApi\Annotations\Schema>

An instance validates successfully against this property if it validates successfully against all schemas
defined by this property's value.

anyOf : array<Schema|\OpenApi\Annotations\Schema>

An instance validates successfully against this property if it validates successfully against at least one
schema defined by this property's value.

oneOf : array<Schema|\OpenApi\Annotations\Schema>

An instance validates successfully against this property if it validates successfully against exactly one schema
defined by this property's value.

additionalProperties : OpenApi\Attributes\AdditionalProperties|bool|null

http://json-schema.org/latest/json-schema-validation.html#anchor64.

const : mixed|null

http://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.1.3.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

SecurityScheme

Allowed in

Components

Nested elements

Flow, Attachable

Parameters

ref : string|class-string|object|null

The relative or absolute path to a security scheme.

See: Using refs

securityScheme : string|null

The key into OpenApi->security array.

type : string|non-empty-array<string>|null

The type of the security scheme.

description : string|null

A short description for security scheme.

name : string|null

The name of the header or query parameter to be used.

in : string|null

Required The location of the API key.

bearerFormat : string|null

A hint to the client to identify how the bearer token is formatted.

Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.

scheme : string|null

The name of the HTTP Authorization scheme.

See: RFC7235

openIdConnectUrl : string|null

OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL.

flows : Flow[]

The flow used by the OAuth2 security scheme.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Server

Allowed in

OpenApi, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace, Link

Nested elements

ServerVariable, Attachable

Parameters

url : string|null

An URL to the target host.

This URL supports Server Variables and may be relative,
to indicate that the host location is relative to the location where the OpenAPI document is being served.
Variable substitutions will be made when a variable is named in {brackets}.

description : string|null

An optional string describing the host designated by the URL.

CommonMark syntax may be used for rich text representation.

variables : ServerVariable[]

A map between a variable name and its value.

The value is used for substitution in the server's URL template.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

ServerVariable

Allowed in

Server

Nested elements

Attachable

Parameters

serverVariable : string|null

The key into Server->variables array.

description : string|null

An optional description for the server variable.

CommonMark syntax MAY be used for rich text representation.

default : string|null

The default value to use for substitution, and to send, if an alternate value is not supplied.

Unlike the Schema Object's default, this value must be provided by the consumer.

enum : array<string|int|float|bool|\UnitEnum|null>|class-string|null

An enumeration of values to be used if the substitution options are from a limited set.

variables : array|null

A map between a variable name and its value.

The value is used for substitution in the server's URL template.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Tag

Allowed in

OpenApi

Nested elements

ExternalDocumentation, Attachable

Parameters

name : string|null

The name of the tag.

description : string|null

A short description for the tag. GFM syntax can be used for rich text representation.

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this tag.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Trace

Allowed in

PathItem

Nested elements

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters

path : string|null

Key in the OpenApi "Paths Object" for this operation.

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

summary : string|null

A short summary of what the operation does.

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

requestBody : OpenApi\Attributes\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

responses : Response[]

The list of possible responses as they are returned from executing this operation.

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this operation.

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Webhook

Allowed in

OpenApi

Nested elements

Get, Post, Put, Delete, Patch, Trace, Head, Options, Parameter, PathParameter, Server, Attachable

Parameters

webhook : string|null

Key for the webhooks map.

path : string|null

Key for the Path Object (OpenApi->paths array).

ref : string|class-string|object|null

No details available.

See: Using refs

summary : string|null

An optional, string summary, intended to apply to all operations in this path.

description : string|null

An optional, string description, intended to apply to all operations in this path.

get : OpenApi\Attributes\Get|null

A definition of a GET operation on this path.

put : OpenApi\Attributes\Put|null

A definition of a PUT operation on this path.

post : OpenApi\Attributes\Post|null

A definition of a POST operation on this path.

delete : OpenApi\Attributes\Delete|null

A definition of a DELETE operation on this path.

options : OpenApi\Attributes\Options|null

A definition of a OPTIONS operation on this path.

head : OpenApi\Attributes\Head|null

A definition of a HEAD operation on this path.

patch : OpenApi\Attributes\Patch|null

A definition of a PATCH operation on this path.

trace : OpenApi\Attributes\Trace|null

A definition of a TRACE operation on this path.

servers : Server[]|null

An alternative server array to service all operations in this path.

parameters : Parameter[]|null

A list of parameters that are applicable for all the operations described under this path.

These parameters can be overridden at the operation level, but cannot be removed there.
The list must not include duplicated parameters.
A unique parameter is defined by a combination of a name and location.
The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's components/parameters.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Xml

Allowed in

AdditionalProperties, Schema, Property, Schema, Items, XmlContent

Nested elements

Attachable

Parameters

name : string|null

Replaces the name of the element/attribute used for the described schema property.

When defined within the Items Object (items), it will affect the name of the individual XML elements within the list.
When defined alongside type being array (outside the items), it will affect the wrapping element
and only if wrapped is true.

If wrapped is false, it will be ignored.

namespace : string|null

The URL of the namespace definition. Value SHOULD be in the form of a URL.

prefix : string|null

The prefix to be used for the name.

attribute : bool|null

Declares whether the property definition translates to an attribute instead of an element.

Default value is false.

wrapped : bool|null

MAY be used only for an array definition.

Signifies whether the array is wrapped (for example <books><book/><book/></books>)
or unwrapped (<book/><book/>).

Default value is false. The definition takes effect only when defined alongside type being array (outside the items).

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

XmlContent

Nested elements

Discriminator, Items, Property, ExternalDocumentation, Xml, AdditionalProperties, Examples, Attachable

Parameters

examples : array<Examples>

Examples of the schema.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

See: Using refs

schema : string|null

The key into Components->schemas array.

title : string|null

Can be used to decorate a user interface with information about the data produced by this user interface.

Preferably short; use description for more details.

description : string|null

A description will provide explanation about the purpose of the instance described by this schema.

maxProperties : int|null

The maximum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is less than, or equal to, the
value of this attribute.

minProperties : int|null

The minimum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is greater than, or equal to, the
value of this attribute.

required : string[]

An object instance is valid against this property if its property set contains all elements in this property's
array value.

properties : Property[]

A collection of properties to define for an object.

Each property is represented as an instance of the Property class.

type : string|non-empty-array<string>|null

The type of the schema/property.

OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".

Since OpenApi v3.1 an array of types may be used.

format : string|null

The extending format for the previously mentioned type. See Data Type Formats for further details.

items : OpenApi\Attributes\Items|null

Required if type is "array". Describes the type of items in the array.

collectionFormat : string|null

Determines the format of the array if type array is used.

Possible values are:
- csv: comma separated values foo,bar.
- ssv: space separated values foo bar.
- tsv: tab separated values foo\tbar.
- pipes: pipe separated values foo|bar.
- multi: corresponds to multiple parameter instances instead of multiple values for a single instance
foo=bar&foo=baz. This is valid only for parameters of type query or formData. Default
value is csv.

default : mixed|null

Sets a default value to the parameter. The type of the value depends on the defined type.

See: JSON schema validation

maximum : int|float

The maximum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMaximum : int|float|bool|null

A boolean indicating whether the maximum value is excluded from the set of valid values.

When set to true, the maximum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

minimum : int|float

The minimum value allowed for a numeric property. This value must be a number.

See: JSON schema validation

exclusiveMinimum : int|float|bool|null

A boolean indicating whether the minimum value is excluded from the set of valid values.

When set to true, the minimum value is excluded, and when false or not specified, it is included.

See: JSON schema validation

maxLength : int|null

The maximum length of a string property.

A string instance is valid against this property if its length is less than, or equal to, the value of this
attribute.

See: JSON schema validation

minLength : int|null

The minimum length of a string property.

A string instance is valid against this property if its length is greater than, or equal to, the value of this
attribute.

See: JSON schema validation

maxItems : int|null

The maximum number of items allowed in an array property.

An array instance is valid against this property if its number of items is less than, or equal to, the value of
this attribute.

See: JSON schema validation

minItems : int|null

The minimum number of items allowed in an array property.

An array instance is valid against this property if its number of items is greater than, or equal to, the value
of this attribute.

See: JSON schema validation

uniqueItems : bool|null

A boolean value indicating whether all items in an array property must be unique.

If this attribute is set to true, then all items in the array must be unique.

See: JSON schema validation

pattern : string|null

A string instance is considered valid if the regular expression matches the instance successfully.

enum : array<string|int|float|bool|\UnitEnum|null>|class-string|null

A collection of allowable values for a property.

A property instance is valid against this attribute if its value is one of the values specified in this
collection.

See: JSON schema validation

discriminator : OpenApi\Attributes\Discriminator|null

Adds support for polymorphism.

The discriminator is an object name that is used to differentiate between other schemas which may satisfy the
payload description. See Composition and Inheritance for more details.

readOnly : bool|null

Declares the property as "read only".

Relevant only for Schema "properties" definitions.

This means that it may be sent as part of a response but should not be sent as part of the request.
If the property is marked as readOnly being true and is in the required list, the required will take effect on
the response only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

writeOnly : bool|null

Declares the property as "write only".

Relevant only for Schema "properties" definitions.
Therefore, it may be sent as part of a request but should not be sent as part of the response.
If the property is marked as writeOnly being true and is in the required list, the required will take effect on
the request only. A property must not be marked as both readOnly and writeOnly being true. Default value is
false.

xml : OpenApi\Attributes\Xml|null

This may be used only on properties schemas.

It has no effect on root schemas.
Adds additional metadata to describe the XML representation of this property.

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this schema.

example : mixed|null

A free-form property to include an example of an instance for this schema.

To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
contain the example with escaping where necessary.

nullable : bool|null

Allows sending a null value for the defined schema.
Default value is false.

This must not be used when using OpenApi version 3.1,
instead make the "type" property an array and add "null" as a possible type.

deprecated : bool|null

Specifies that a schema is deprecated and should be transitioned out of usage.
Default value is false.

allOf : array<Schema|\OpenApi\Annotations\Schema>

An instance validates successfully against this property if it validates successfully against all schemas
defined by this property's value.

anyOf : array<Schema|\OpenApi\Annotations\Schema>

An instance validates successfully against this property if it validates successfully against at least one
schema defined by this property's value.

oneOf : array<Schema|\OpenApi\Annotations\Schema>

An instance validates successfully against this property if it validates successfully against exactly one schema
defined by this property's value.

additionalProperties : OpenApi\Attributes\AdditionalProperties|bool|null

http://json-schema.org/latest/json-schema-validation.html#anchor64.

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

+ + + + + \ No newline at end of file diff --git a/reference/generator.html b/reference/generator.html new file mode 100644 index 000000000..80c43b499 --- /dev/null +++ b/reference/generator.html @@ -0,0 +1,100 @@ + + + + + + Using the Generator | Swagger-PHP + + + + + + + + + +
Swagger-PHP

Using the Generator

Introduction

The Generator class provides an object-oriented way to use swagger-php and all its aspects in a single place.

The \OpenApi\scan() function

For a long time the \OpenApi\scan() function was the main entry point into using swagger-php from PHP code.

/**
+  * Scan the filesystem for OpenAPI annotations and build openapi-documentation.
+  *
+  * @param array|Finder|string $directory The directory(s) or filename(s)
+  * @param array               $options
+  *                                       exclude: string|array $exclude The directory(s) or filename(s) to exclude (as absolute or relative paths)
+  *                                       pattern: string       $pattern File pattern(s) to scan (default: *.php)
+  *                                       analyser: defaults to StaticAnalyser
+  *                                       analysis: defaults to a new Analysis
+  *                                       processors: defaults to the registered processors in Analysis
+  *
+  * @return OpenApi
+  */
+  function scan($directory, $options = []) { /* ... */ }
+

Using it looked typically something like this:

require("vendor/autoload.php");
+
+$openapi = \OpenApi\scan(__DIR__, ['exclude' => ['tests'], 'pattern' => '*.php']);
+

The two configuration options for the underlying Doctrine doc-block parser aliases and namespaces are not part of this function and need to be set separately.

Being static this means setting them back is the callers responsibility and there is also the fact that some Doctrine configuration currently can not be reverted easily.

Therefore, having a single side effect free way of using swagger-php seemed like a good idea...

The \OpenApi\Generator class

The Generator class can be used in object-oriented (and fluent) style which allows for easy customization if needed.

In that case to actually process the given input files the non-static method generate() is to be used.

Full example of using the Generator class to generate OpenApi specs.

require("vendor/autoload.php");
+
+$validate = true;
+$logger = new \Psr\Log\NullLogger();
+$processors = [/* my processors */];
+$finder = \Symfony\Component\Finder\Finder::create()->files()->name('*.php')->in(__DIR__);
+
+$openapi = (new \OpenApi\Generator($logger))
+            ->setProcessors($processors)
+            ->setAliases(['MY' => 'My\Annotations'])
+            ->setNamespaces(['My\\Annotations\\'])
+            ->setAnalyser(new \OpenApi\Analysers\TokenAnalyser())
+            ->setVersion(\OpenApi\Annotations\OpenApi::VERSION_3_0_0)
+            ->generate(['/path1/to/project', $finder], new \OpenApi\Analysis(), $validate);
+

Aliases and namespaces are additional options that allow to customize the parsing of docblocks.

Defaults:

  • aliases: ['oa' => 'OpenApi\\Annotations']

    Aliases help the underlying doctrine annotations library to parse annotations. Effectively they avoid having to write use OpenApi\Annotations as OA; in your code and make @OA\property(..) annotations still work.

  • namespaces: ['OpenApi\\Annotations\\']

    Namespaces control which annotation namespaces can be autoloaded automatically. Under the hood this is handled by registering a custom loader with the doctrine annotation library.

Advantages:

  • The Generator code will handle configuring things as before in a single place
  • Static settings will be reverted to the default once finished
  • The get/set methods allow for using type hints
  • Static configuration is deprecated and can be removed at some point without code changes
  • Build in support for PSR logger
  • Support for Symfony Finder, \SplInfo and file/directory names (`string) as source.

The minimum code required, using the generate() method, looks quite similar to the old scan() code:

    /**
+     * Generate OpenAPI spec by scanning the given source files.
+     *
+     * @param iterable      $sources  PHP source files to scan.
+     *                                Supported sources:
+     *                                * string - file / directory name
+     *                                * \SplFileInfo
+     *                                * \Symfony\Component\Finder\Finder
+     * @param null|Analysis $analysis custom analysis instance
+     * @param bool          $validate flag to enable/disable validation of the returned spec
+     */
+    public function generate(iterable $sources, ?Analysis $analysis = null, bool $validate = true): \OpenApi\OpenApi { /* ... */ }
+
require("vendor/autoload.php");
+
+$openapi = (new \OpenApi\Generator())->generate(['/path1/to/project']);
+

For those that want to type even less and keep using a plain array to configure swagger-php there is also a static version:

<?php
+require("vendor/autoload.php");
+
+$openapi = \OpenApi\Generator::scan(['/path/to/project']);
+
+header('Content-Type: application/x-yaml');
+echo $openapi->toYaml();
+

Note: While using the same name as the old scan() function, the Generator::scan method is not 100% backwards compatible.

    /**
+     * Static  wrapper around `Generator::generate()`.
+     *
+     * @param iterable $sources PHP source files to scan.
+     *                          Supported sources:
+     *                          * string
+     *                          * \SplFileInfo
+     *                          * \Symfony\Component\Finder\Finder
+     * @param array    $options
+     *                          aliases:    null|array                    Defaults to `['oa' => 'OpenApi\\Annotations']`.
+     *                          namespaces: null|array                    Defaults to `['OpenApi\\Annotations\\']`.
+     *                          analyser:   null|AnalyserInterface        Defaults to a new `ReflectionAnalyser` supporting both docblocks and attributes.
+     *                          analysis:   null|Analysis                 Defaults to a new `Analysis`.
+     *                          processors: null|array                    Defaults to `Analysis::processors()`.
+     *                          logger:     null|\Psr\Log\LoggerInterface If not set logging will use \OpenApi\Logger as before.
+     *                          validate:   bool                          Defaults to `true`.
+     */
+    public static function scan(iterable $sources, array $options = []): OpenApi { /* ... */ }
+

Most notably the exclude and pattern keys are no longer supported. Instead, a Symfony Finder instance can be passed in as source directly (same as with Generator::generate()).

If needed, the \OpenApi\Util class provides a builder method that allows to keep the status-quo

$exclude = ['tests'];
+$pattern = '*.php';
+
+$openapi = \OpenApi\Generator::scan(\OpenApi\Util::finder(__DIR__, $exclude, $pattern));
+
+// same as
+
+$openapi = \OpenApi\scan(__DIR__, ['exclude' => $exclude, 'pattern' => $pattern]);
+
+ + + + + \ No newline at end of file diff --git a/reference/index.html b/reference/index.html new file mode 100644 index 000000000..58a41b685 --- /dev/null +++ b/reference/index.html @@ -0,0 +1,21 @@ + + + + + + Reference | Swagger-PHP + + + + + + + + + +
Swagger-PHP

Reference

In total there are a number of different aspects to using swagger-php. Depending on how custom your requirements are this might be limited to just annotating your code and using the command line tool.

However, swagger-php offers more.

  • Attributes

    The new way of adding meta-data to your codebase. Requires PHP 8.1

  • Docblock annotations

    The 'traditional' way of documenting your API.

  • The Generator

    The \OpenAPI\Generator class is the main entry point to programmatically generate OpenAPI documents from your code.

  • Processors

    swagger-php comes with a list of pre-defined processors that convert the raw data to a complete OpenAPI document. Custom processors can be added or existing removed to tweak swagger-php` to your requirements.

+ + + + + \ No newline at end of file diff --git a/reference/processors.html b/reference/processors.html new file mode 100644 index 000000000..1273cbe73 --- /dev/null +++ b/reference/processors.html @@ -0,0 +1,21 @@ + + + + + + Processors | Swagger-PHP + + + + + + + + + +
Swagger-PHP

Processors

This page is generated automatically from the swagger-php sources.

For improvements head over to GitHub and create a PR 😉

DocBlockDescriptions

Checks if the annotation has a summary and/or description property and uses the text in the comment block (above the annotations) as summary and/or description.

Use null, for example: @Annotation(description=null), if you don't want the annotation to have a description.

MergeIntoOpenApi

Merge all @OA\OpenApi annotations into one.

MergeIntoComponents

Merge reusable annotation into @OA\Schemas.

ExpandClasses

Iterate over the chain of ancestors of a schema and:

  • if the ancestor has a schema => inherit from the ancestor if it has a schema (allOf) and stop.
  • else => merge ancestor properties into the schema.

ExpandInterfaces

Look at all (direct) interfaces for a schema and:

  • merge interfaces annotations/methods into the schema if the interface does not have a schema itself
  • inherit from the interface if it has a schema (allOf).

ExpandTraits

Look at all (direct) traits for a schema and:

  • merge trait annotations/methods/properties into the schema if the trait does not have a schema itself
  • inherit from the trait if it has a schema (allOf).

ExpandEnums

Expands PHP enums.

Determines schema, enum and type.

AugmentSchemas

Use the Schema context to extract useful information and inject that into the annotation.

Merges properties.

AugmentRequestBody

Use the RequestBody context to extract useful information and inject that into the annotation.

AugmentProperties

Use the property context to extract useful information and inject that into the annotation.

BuildPaths

Build the openapi->paths using the detected @OA\PathItem and @OA\Operation (@OA\Get, @OA\Post, etc).

AugmentParameters

Config settings

augmentParameters.augmentOperationParameters : bool

No details available.

AugmentRefs

MergeJsonContent

Split JsonContent into Schema and MediaType.

MergeXmlContent

Split XmlContent into Schema and MediaType.

OperationId

Generate the OperationId based on the context of the OpenApi annotation.

Config settings

operationId.hash : bool

No details available.

CleanUnmerged

CleanUnusedComponents

+ + + + + \ No newline at end of file diff --git a/related-projects.html b/related-projects.html new file mode 100644 index 000000000..4787eae61 --- /dev/null +++ b/related-projects.html @@ -0,0 +1,21 @@ + + + + + + Related projects | Swagger-PHP + + + + + + + + + +
Swagger-PHP

Related projects

ProjectDescription
Swagger UIThe webinterface for reading the generated documentation
Swagger ExplainedBrowse the spec by using an swagger.json.
silex2swaggerGenerate swagger documentation from Silex Annotations
yii2-swaggerswagger-php integration with yii2
Lumen swaggerswagger-php integration with lumen/laravel
NelmioApiDocBundleSymfony bundle on top of swagger-php
auto-swagger-uiAutomatically add swagger ui and json to your application
openapi-routerConfigure framework routes from OpenApi annotations
openapi-verifierVerify response against OpenAPI specification in PHPUnit
openapi-filterFilter internal paths, operations, parameters, etc
OpenAPI-Symfony-RoutingLoad routes in Symfony based on OpenAPI annotations
Swag It PHPConvert JSON to PHP Swagger annotations
Laravel SwaggerOpenApi or Swagger integration to Laravel
openapi-extrasExtra annotations for swagger-php
openapi-serializeSerialize an object using swagger-php

Is a related project missing? Create a pull request!

+ + + + + \ No newline at end of file