OpenAPI
مرور کلی
شورت‌کد openapi یک توصیف OpenAPI را با Swagger UI به‌صورت یک مرجع تعاملی API نمایش می‌دهد. خوانندگان می‌توانند عملیات، پارامترها و اسکیماها را مرور کنند و درخواست‌ها را مستقیماً از صفحه امتحان کنند. Swagger UI از پوسته‌های روشن و تیره سایت پیروی می‌کند.
مثال
استفاده
توصیف OpenAPI را با قالب JSON یا YAML به‌عنوان پارامتر اول یا با src ارسال کنید. این توصیف می‌تواند فایلی در پوشه assets/، منبعی از بسته صفحه، فایلی در پوشه static/ با مسیری که با / شروع می‌شود، یا یک URL باشد:
{{< openapi "openapi/example.yaml" >}}
{{< openapi src="https://petstore3.swagger.io/api/v3/openapi.json" >}}فایل‌های محلی همراه با سایت منتشر می‌شوند، اما فایل‌هایی که توصیف با $ref به آن‌ها ارجاع می‌دهد منتشر نمی‌شوند: آن‌ها را نیز منتشر کنید، برای مثال در پوشه static/. مرورگر توصیف‌های راه دور را مستقیماً دریافت می‌کند، بنابراین سرور باید درخواست‌های بین‌مبدأ را مجاز کند.
Swagger UI به فضای عریض نیاز دارد: برای فضای بیشتر، width: wide یا width: full را در front matter صفحه تنظیم کنید. همچنین Swagger UI از شناسه‌های ثابت برای عناصر استفاده می‌کند، بنابراین در هر صفحه فقط یک توصیف نمایش دهید.
گزینه‌ها
| پارامتر | توضیحات |
|---|---|
src | توصیف OpenAPI. می‌توان آن را به‌عنوان پارامتر اول نیز ارسال کرد. |
docExpansion | نحوه باز شدن عملیات: list (پیش‌فرض)، full یا none. |
defaultModelsExpandDepth | عمق باز شدن بخش اسکیماها. مقدار -1 آن را پنهان می‌کند. پیش‌فرض 1 است. |
filter | نمایش فیلدی برای فیلتر کردن عملیات بر اساس برچسب. پیش‌فرض false است. |
tryItOutEnabled | باز کردن بخش «Try it out» عملیات به‌صورت پیش‌فرض. پیش‌فرض false است. |
tagsSorter | مقدار alpha برچسب‌ها را به ترتیب الفبا مرتب می‌کند. پیش‌فرض ترتیب توصیف است. |
operationsSorter | مقدار alpha یا method عملیات را مرتب می‌کند. پیش‌فرض ترتیب توصیف است. |
{{< openapi src="openapi/example.yaml" docExpansion="none" filter=true tagsSorter="alpha" >}}فایل‌های Swagger UI
Swagger UI فقط در صفحاتی بارگذاری می‌شود که از این شورت‌کد استفاده می‌کنند. به‌طور پیش‌فرض، Hextra آن را هنگام ساخت از jsDelivr دریافت می‌کند و همراه با سایت منتشر می‌کند. برای استفاده از آینه یا فایل‌های محلی، به اسکریپت‌های محلی و آینه‌شده مراجعه کنید.