davlgd · Sep 30, 2026 · Oct 6, 2026 · Oct 6, 2026
diff --git a/assets/css/compiled/main.css b/assets/css/compiled/main.css
diff --git a/assets/css/components/openapi.css b/assets/css/components/openapi.css
@@ -0,0 +1,50 @@
+/* Swagger UI rendered by the openapi shortcode. Its stylesheet loads after
+   this one, so overrides add .hextra-openapi to win over the same selector. */
+
+.hextra-openapi {
+  @apply hx:my-6;
+}
+
+.hextra-openapi .swagger-ui .wrapper {
+  @apply hx:px-0;
+}
+
+/* Swagger UI paints its dark theme on a blue-gray background, including the
+   root element: keep the Hextra page background */
+:root.dark-mode,
+html.dark-mode .hextra-openapi .swagger-ui {
+  background: transparent;
+}
+
+/* Keyboard focus: Swagger UI removes the outline of selects, and its dark
+   theme also removes it from operation and schema toggles, with rules up to
+   six classes deep, hence !important */
+.hextra-openapi .swagger-ui select:focus-visible,
+.hextra-openapi .swagger-ui .opblock-summary-control:focus-visible,
+.hextra-openapi .swagger-ui .model-box-control:focus-visible,
+.hextra-openapi .swagger-ui .models-control:focus-visible {
+  outline: 2px solid var(--hx-color-primary-500) !important;
+  outline-offset: 2px;
+}
+
+/* Deprecated operations: Swagger UI dims them to 60% opacity, which takes
+   their text and badge below 3:1 in both themes. The struck-through path and
+   the gray badge already mark them, so keep them opaque and darken or lighten
+   the badge enough for its label. */
+.hextra-openapi .swagger-ui .opblock.opblock-deprecated {
+  opacity: 1;
+}
+
+.hextra-openapi .swagger-ui .opblock.opblock-deprecated .opblock-summary-method {
+  background: rgb(115 115 115);
+}
+
+html.dark-mode .hextra-openapi .swagger-ui .opblock.opblock-deprecated .opblock-summary-method {
+  background: rgb(212 212 212);
+}
+
+/* In the Swagger UI dark theme, the PUT section header is far lighter than
+   those of the other methods and its text stays below 4.5:1 */
+html.dark-mode .hextra-openapi .swagger-ui .opblock.opblock-put .opblock-section-header {
+  background: #3b2a1d;
+}
diff --git a/assets/css/styles.css b/assets/css/styles.css
@@ -102,3 +102,4 @@ body {
 @import "./components/toc.css";
 @import "./components/archives.css";
 @import "./components/gallery.css";
+@import "./components/openapi.css";
diff --git a/docs/assets/openapi/example.yaml b/docs/assets/openapi/example.yaml
@@ -0,0 +1,138 @@
+openapi: 3.1.0
+info:
+  title: Bookshelf API
+  version: 1.0.0
+  description: A small example API to showcase the `openapi` shortcode.
+servers:
+  - url: https://api.example.com/v1
+tags:
+  - name: Books
+    description: Manage the books of the shelf
+paths:
+  /books:
+    get:
+      tags: [Books]
+      summary: List books
+      parameters:
+        - name: author
+          in: query
+          description: Only return books written by this author
+          schema:
+            type: string
+        - name: limit
+          in: query
+          description: Maximum number of books to return
+          schema:
+            type: integer
+            default: 20
+      responses:
+        "200":
+          description: The books of the shelf
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Book"
+    post:
+      tags: [Books]
+      summary: Add a book
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/NewBook"
+      responses:
+        "201":
+          description: The book was added
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Book"
+  /books/{bookId}:
+    parameters:
+      - name: bookId
+        in: path
+        required: true
+        description: Identifier of the book
+        schema:
+          type: string
+    get:
+      tags: [Books]
+      summary: Get a book
+      responses:
+        "200":
+          description: The book
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Book"
+        "404":
+          description: No book has this identifier
+    put:
+      tags: [Books]
+      summary: Replace a book
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/NewBook"
+      responses:
+        "200":
+          description: The updated book
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Book"
+    delete:
+      tags: [Books]
+      summary: Remove a book
+      responses:
+        "204":
+          description: The book was removed
+  /books/{bookId}/cover:
+    get:
+      tags: [Books]
+      summary: Get the cover of a book
+      deprecated: true
+      description: Use the `coverUrl` property of the book instead.
+      parameters:
+        - name: bookId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The cover image
+          content:
+            image/png: {}
+components:
+  schemas:
+    NewBook:
+      type: object
+      required: [title, author]
+      properties:
+        title:
+          type: string
+          example: The Hobbit
+        author:
+          type: string
+          example: J. R. R. Tolkien
+        year:
+          type: integer
+          example: 1937
+    Book:
+      allOf:
+        - $ref: "#/components/schemas/NewBook"
+        - type: object
+          required: [id]
+          properties:
+            id:
+              type: string
+              example: hobbit
+            coverUrl:
+              type: string
+              format: uri
diff --git a/docs/content/docs/guide/configuration.fa.md b/docs/content/docs/guide/configuration.fa.md
@@ -378,6 +378,10 @@ params:
     lightboxJs: "js/vendor/photoswipe-lightbox.esm.min.js"
     css: "css/vendor/photoswipe.css"
 
+  openapi:
+    js: "js/vendor/swagger-ui-bundle.js"
+    css: "css/vendor/swagger-ui.css"
+
   math:
     engine: katex
     katex:
@@ -411,6 +415,9 @@ params:
   gallery:
     base: "https://mirror.example.com/photoswipe/dist"
 
+  openapi:
+    base: "https://mirror.example.com/swagger-ui-dist"
+
   math:
     engine: katex
     katex:

diff --git a/docs/content/docs/guide/configuration.ja.md b/docs/content/docs/guide/configuration.ja.md
@@ -378,6 +378,10 @@ params:
     lightboxJs: "js/vendor/photoswipe-lightbox.esm.min.js"
     css: "css/vendor/photoswipe.css"
 
+  openapi:
+    js: "js/vendor/swagger-ui-bundle.js"
+    css: "css/vendor/swagger-ui.css"
+
   math:
     engine: katex
     katex:
@@ -411,6 +415,9 @@ params:
   gallery:
     base: "https://mirror.example.com/photoswipe/dist"
 
+  openapi:
+    base: "https://mirror.example.com/swagger-ui-dist"
+
   math:
     engine: katex
     katex:

diff --git a/docs/content/docs/guide/configuration.md b/docs/content/docs/guide/configuration.md
@@ -414,6 +414,10 @@ params:
     lightboxJs: "js/vendor/photoswipe-lightbox.esm.min.js"
     css: "css/vendor/photoswipe.css"
 
+  openapi:
+    js: "js/vendor/swagger-ui-bundle.js"
+    css: "css/vendor/swagger-ui.css"
+
   math:
     engine: katex
     katex:
@@ -447,6 +451,9 @@ params:
   gallery:
     base: "https://mirror.example.com/photoswipe/dist"
 
+  openapi:
+    base: "https://mirror.example.com/swagger-ui-dist"
+
   math:
     engine: katex
     katex:

diff --git a/docs/content/docs/guide/configuration.zh-cn.md b/docs/content/docs/guide/configuration.zh-cn.md
@@ -378,6 +378,10 @@ params:
     lightboxJs: "js/vendor/photoswipe-lightbox.esm.min.js"
     css: "css/vendor/photoswipe.css"
 
+  openapi:
+    js: "js/vendor/swagger-ui-bundle.js"
+    css: "css/vendor/swagger-ui.css"
+
   math:
     engine: katex
     katex:
@@ -411,6 +415,9 @@ params:
   gallery:
     base: "https://mirror.example.com/photoswipe/dist"
 
+  openapi:
+    base: "https://mirror.example.com/swagger-ui-dist"
+
   math:
     engine: katex
     katex:

diff --git a/docs/content/docs/guide/shortcodes/_index.fa.md b/docs/content/docs/guide/shortcodes/_index.fa.md
@@ -28,4 +28,5 @@ Hextra مجموعه‌ای از شورت‌کدهای زیبا را برای ب
   {{< card link="others" title="سایر" icon="view-grid" >}}
   {{< card link="asciinema" title="Asciinema Player" icon="terminal" >}}
   {{< card link="gallery" title="گالری تصاویر" icon="photograph" >}}
+  {{< card link="openapi" title="OpenAPI" icon="code" >}}
 {{< /cards >}}
diff --git a/docs/content/docs/guide/shortcodes/_index.ja.md b/docs/content/docs/guide/shortcodes/_index.ja.md
@@ -28,4 +28,5 @@ Hugo と Hextra が提供する追加のショートコード:
   {{< card link="others" title="Others" icon="view-grid" >}}
   {{< card link="asciinema" title="Asciinema Player" icon="terminal" >}}
   {{< card link="gallery" title="画像ギャラリー" icon="photograph" >}}
+  {{< card link="openapi" title="OpenAPI" icon="code" >}}
 {{< /cards >}}
diff --git a/docs/content/docs/guide/shortcodes/_index.md b/docs/content/docs/guide/shortcodes/_index.md
@@ -30,4 +30,5 @@ Additional shortcodes provided by Hugo and Hextra:
   {{< card link="hextra" title="Hextra" icon="view-grid" >}}
   {{< card link="asciinema" title="Asciinema Player" icon="terminal" >}}
   {{< card link="gallery" title="Gallery" icon="photograph" >}}
+  {{< card link="openapi" title="OpenAPI" icon="code" >}}
 {{< /cards >}}
diff --git a/docs/content/docs/guide/shortcodes/_index.zh-cn.md b/docs/content/docs/guide/shortcodes/_index.zh-cn.md
@@ -28,4 +28,5 @@ Hugo 和 Hextra 提供的其他短代码：
   {{< card link="others" title="其他" icon="view-grid" >}}
   {{< card link="asciinema" title="Asciinema Player" icon="terminal" >}}
   {{< card link="gallery" title="图片库" icon="photograph" >}}
+  {{< card link="openapi" title="OpenAPI" icon="code" >}}
 {{< /cards >}}
diff --git a/docs/content/docs/guide/shortcodes/openapi.fa.md b/docs/content/docs/guide/shortcodes/openapi.fa.md
@@ -0,0 +1,48 @@
+---
+title: "OpenAPI"
+linktitle: "OpenAPI"
+width: wide
+sidebar:
+  exclude: true
+---
+
+## مرور کلی
+
+شورت‌کد `openapi` یک توصیف [OpenAPI](https://www.openapis.org/) را با [Swagger UI](https://swagger.io/tools/swagger-ui/) به‌صورت یک مرجع تعاملی API نمایش می‌دهد. خوانندگان می‌توانند عملیات، پارامترها و اسکیماها را مرور کنند و درخواست‌ها را مستقیماً از صفحه امتحان کنند. Swagger UI از پوسته‌های روشن و تیره سایت پیروی می‌کند.
+
+## مثال
+
+{{< openapi "openapi/example.yaml" >}}
+
+## استفاده
+
+توصیف OpenAPI را با قالب JSON یا YAML به‌عنوان پارامتر اول یا با `src` ارسال کنید. این توصیف می‌تواند فایلی در پوشه `assets/`، منبعی از بسته صفحه، فایلی در پوشه `static/` با مسیری که با `/` شروع می‌شود، یا یک URL باشد:
+
+```markdown
+{{</* 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` عملیات را مرتب می‌کند. پیش‌فرض ترتیب توصیف است. |
+
+```markdown
+{{</* openapi src="openapi/example.yaml" docExpansion="none" filter=true tagsSorter="alpha" */>}}
+```
+
+## فایل‌های Swagger UI
+
+Swagger UI فقط در صفحاتی بارگذاری می‌شود که از این شورت‌کد استفاده می‌کنند. به‌طور پیش‌فرض، Hextra آن را هنگام ساخت از jsDelivr دریافت می‌کند و همراه با سایت منتشر می‌کند. برای استفاده از آینه یا فایل‌های محلی، به [اسکریپت‌های محلی و آینه‌شده]({{% relref "docs/guide/configuration#اسکریپتهای-محلی-و-آینهشده" %}}) مراجعه کنید.