From 9ac3e4fcfee7334596c3fbfe8da28e424e224ae6 Mon Sep 17 00:00:00 2001 From: okxlin <61420215+okxlin@users.noreply.github.com> Date: Sun, 19 Jul 2026 10:23:35 +0800 Subject: [PATCH] feat(scalar): add API reference app --- apps/scalar/0.5.58/.env.sample | 2 + apps/scalar/0.5.58/data.yml | 19 +++++++++ apps/scalar/0.5.58/data/docs/example.yaml | 23 +++++++++++ apps/scalar/0.5.58/docker-compose.yml | 17 ++++++++ apps/scalar/0.5.58/scripts/.gitkeep | 0 apps/scalar/0.5.58/scripts/init.sh | 6 +++ apps/scalar/0.5.58/scripts/uninstall.sh | 4 ++ apps/scalar/0.5.58/scripts/upgrade.sh | 3 ++ apps/scalar/README.md | 48 ++++++++++++++++++++++ apps/scalar/data.yml | 30 ++++++++++++++ apps/scalar/latest/.env.sample | 2 + apps/scalar/latest/data.yml | 19 +++++++++ apps/scalar/latest/data/docs/example.yaml | 23 +++++++++++ apps/scalar/latest/docker-compose.yml | 17 ++++++++ apps/scalar/latest/scripts/.gitkeep | 0 apps/scalar/latest/scripts/init.sh | 6 +++ apps/scalar/latest/scripts/uninstall.sh | 4 ++ apps/scalar/latest/scripts/upgrade.sh | 3 ++ apps/scalar/logo.png | Bin 0 -> 1819 bytes 19 files changed, 226 insertions(+) create mode 100644 apps/scalar/0.5.58/.env.sample create mode 100644 apps/scalar/0.5.58/data.yml create mode 100644 apps/scalar/0.5.58/data/docs/example.yaml create mode 100644 apps/scalar/0.5.58/docker-compose.yml create mode 100644 apps/scalar/0.5.58/scripts/.gitkeep create mode 100755 apps/scalar/0.5.58/scripts/init.sh create mode 100755 apps/scalar/0.5.58/scripts/uninstall.sh create mode 100755 apps/scalar/0.5.58/scripts/upgrade.sh create mode 100644 apps/scalar/README.md create mode 100644 apps/scalar/data.yml create mode 100644 apps/scalar/latest/.env.sample create mode 100644 apps/scalar/latest/data.yml create mode 100644 apps/scalar/latest/data/docs/example.yaml create mode 100644 apps/scalar/latest/docker-compose.yml create mode 100644 apps/scalar/latest/scripts/.gitkeep create mode 100755 apps/scalar/latest/scripts/init.sh create mode 100755 apps/scalar/latest/scripts/uninstall.sh create mode 100755 apps/scalar/latest/scripts/upgrade.sh create mode 100644 apps/scalar/logo.png diff --git a/apps/scalar/0.5.58/.env.sample b/apps/scalar/0.5.58/.env.sample new file mode 100644 index 000000000..014810c46 --- /dev/null +++ b/apps/scalar/0.5.58/.env.sample @@ -0,0 +1,2 @@ +PANEL_APP_PORT_HTTP=8080 +CONTAINER_NAME= diff --git a/apps/scalar/0.5.58/data.yml b/apps/scalar/0.5.58/data.yml new file mode 100644 index 000000000..943c748ed --- /dev/null +++ b/apps/scalar/0.5.58/data.yml @@ -0,0 +1,19 @@ +additionalProperties: + formFields: + - default: 8080 + edit: true + envKey: PANEL_APP_PORT_HTTP + labelEn: HTTP Port + labelZh: HTTP 端口 + label: + en: HTTP Port + zh: HTTP 端口 + zh-Hant: HTTP 連接埠 + ja: HTTP ポート + ko: HTTP 포트 + ru: HTTP-порт + ms: Port HTTP + pt-br: Porta HTTP + required: true + rule: paramPort + type: number diff --git a/apps/scalar/0.5.58/data/docs/example.yaml b/apps/scalar/0.5.58/data/docs/example.yaml new file mode 100644 index 000000000..663321168 --- /dev/null +++ b/apps/scalar/0.5.58/data/docs/example.yaml @@ -0,0 +1,23 @@ +openapi: 3.0.3 +info: + title: Scalar API Reference Example + version: 1.0.0 + description: A small OpenAPI document included to verify a fresh Scalar installation. +paths: + /health: + get: + operationId: getHealth + summary: Read the example health response + responses: + '200': + description: The example service is healthy. + content: + application/json: + schema: + type: object + required: + - status + properties: + status: + type: string + example: ok diff --git a/apps/scalar/0.5.58/docker-compose.yml b/apps/scalar/0.5.58/docker-compose.yml new file mode 100644 index 000000000..0126d7de2 --- /dev/null +++ b/apps/scalar/0.5.58/docker-compose.yml @@ -0,0 +1,17 @@ +services: + scalar: + image: "scalarapi/api-reference:0.5.58" + container_name: ${CONTAINER_NAME} + ports: + - "${PANEL_APP_PORT_HTTP}:8080" + volumes: + - ./data/docs:/docs:ro + labels: + createdBy: "Apps" + restart: unless-stopped + networks: + - 1panel-network + +networks: + 1panel-network: + external: true diff --git a/apps/scalar/0.5.58/scripts/.gitkeep b/apps/scalar/0.5.58/scripts/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/apps/scalar/0.5.58/scripts/init.sh b/apps/scalar/0.5.58/scripts/init.sh new file mode 100755 index 000000000..dee14f760 --- /dev/null +++ b/apps/scalar/0.5.58/scripts/init.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" + +mkdir -p "$ROOT_DIR/data/docs" diff --git a/apps/scalar/0.5.58/scripts/uninstall.sh b/apps/scalar/0.5.58/scripts/uninstall.sh new file mode 100755 index 000000000..2662517fe --- /dev/null +++ b/apps/scalar/0.5.58/scripts/uninstall.sh @@ -0,0 +1,4 @@ +#!/usr/bin/env bash +set -euo pipefail + +docker-compose down --volumes diff --git a/apps/scalar/0.5.58/scripts/upgrade.sh b/apps/scalar/0.5.58/scripts/upgrade.sh new file mode 100755 index 000000000..9879df4c3 --- /dev/null +++ b/apps/scalar/0.5.58/scripts/upgrade.sh @@ -0,0 +1,3 @@ +#!/usr/bin/env bash +set -euo pipefail +exit 0 diff --git a/apps/scalar/README.md b/apps/scalar/README.md new file mode 100644 index 000000000..e89d526f9 --- /dev/null +++ b/apps/scalar/README.md @@ -0,0 +1,48 @@ +# Scalar API Reference + +## 产品介绍 + +Scalar API Reference 从 OpenAPI 和 Swagger 规范提供交互式 API 参考文档。本应用使用 +官方 `scalarapi/api-reference` 镜像及其 `/docs` 文档扫描机制。 + +## 主要功能 + +- 在浏览器中展示和交互浏览 OpenAPI 文档。 +- 自动识别 `data/docs` 中的 JSON、YAML 和 YML 规范文件。 +- 预置非敏感示例规范，首次安装后即可验证服务和文档扫描。 + +## 访问说明 + +- 安装后访问 `http://<服务器 IP>:`。 +- 首次安装包含一个示例 OpenAPI 文档，用于确认参考文档界面和文档扫描正常工作。 +- 在应用安装目录的 `data/docs` 中添加或替换 `.json`、`.yaml` 或 `.yml` + OpenAPI 文件，然后重启应用。Scalar 会自动在页面中列出有效的规范文件。 +- `data/docs` 为用户文档目录；卸载应用不会删除其中的文件。 + +## Usage + +- Open `http://:` after installation. +- The first installation includes a small OpenAPI example to verify the UI and + document scan without additional setup. +- Add or replace `.json`, `.yaml`, or `.yml` OpenAPI documents in the installed + app's `data/docs` directory, then restart the app. Scalar lists valid + specifications automatically. +- `data/docs` contains user documentation and is preserved on uninstall. + +## Introduction + +Scalar API Reference serves interactive API documentation from OpenAPI and +Swagger specifications. This package uses the official +`scalarapi/api-reference` image and its documented `/docs` document scan. + +## Features + +- Display and interact with OpenAPI documents in a browser. +- Discover JSON, YAML, and YML specification files in `data/docs`. +- Include a non-sensitive example specification so a new install can verify the + service and document scan immediately. + +## Sources + +- [Scalar Docker integration](https://scalar.com/products/api-references/integrations/docker) +- [Scalar source repository](https://github.com/scalar/scalar) diff --git a/apps/scalar/data.yml b/apps/scalar/data.yml new file mode 100644 index 000000000..3a0d582a1 --- /dev/null +++ b/apps/scalar/data.yml @@ -0,0 +1,30 @@ +name: Scalar API Reference +tags: +- Tool +title: Scalar API 参考文档 +description: Scalar API 参考文档 +additionalProperties: + key: scalar + name: Scalar API Reference + tags: + - Tool + shortDescZh: Scalar API 参考文档 + shortDescEn: Scalar API reference + description: + en: Serve interactive API reference documentation from OpenAPI specifications. + zh: 从 OpenAPI 规范提供交互式 API 参考文档。 + zh-Hant: 從 OpenAPI 規範提供互動式 API 參考文件。 + ja: OpenAPI 仕様から対話型 API リファレンスを提供します。 + ko: OpenAPI 사양에서 대화형 API 참조 문서를 제공합니다. + ru: Предоставляет интерактивную справку API из спецификаций OpenAPI. + ms: Menyediakan rujukan API interaktif daripada spesifikasi OpenAPI. + pt-br: Disponibiliza referencia interativa de API a partir de especificacoes OpenAPI. + type: tool + crossVersionUpdate: true + limit: 0 + website: https://scalar.com + github: https://github.com/scalar/scalar + document: https://scalar.com/products/api-references/integrations/docker + architectures: + - amd64 + - arm64 diff --git a/apps/scalar/latest/.env.sample b/apps/scalar/latest/.env.sample new file mode 100644 index 000000000..014810c46 --- /dev/null +++ b/apps/scalar/latest/.env.sample @@ -0,0 +1,2 @@ +PANEL_APP_PORT_HTTP=8080 +CONTAINER_NAME= diff --git a/apps/scalar/latest/data.yml b/apps/scalar/latest/data.yml new file mode 100644 index 000000000..943c748ed --- /dev/null +++ b/apps/scalar/latest/data.yml @@ -0,0 +1,19 @@ +additionalProperties: + formFields: + - default: 8080 + edit: true + envKey: PANEL_APP_PORT_HTTP + labelEn: HTTP Port + labelZh: HTTP 端口 + label: + en: HTTP Port + zh: HTTP 端口 + zh-Hant: HTTP 連接埠 + ja: HTTP ポート + ko: HTTP 포트 + ru: HTTP-порт + ms: Port HTTP + pt-br: Porta HTTP + required: true + rule: paramPort + type: number diff --git a/apps/scalar/latest/data/docs/example.yaml b/apps/scalar/latest/data/docs/example.yaml new file mode 100644 index 000000000..663321168 --- /dev/null +++ b/apps/scalar/latest/data/docs/example.yaml @@ -0,0 +1,23 @@ +openapi: 3.0.3 +info: + title: Scalar API Reference Example + version: 1.0.0 + description: A small OpenAPI document included to verify a fresh Scalar installation. +paths: + /health: + get: + operationId: getHealth + summary: Read the example health response + responses: + '200': + description: The example service is healthy. + content: + application/json: + schema: + type: object + required: + - status + properties: + status: + type: string + example: ok diff --git a/apps/scalar/latest/docker-compose.yml b/apps/scalar/latest/docker-compose.yml new file mode 100644 index 000000000..a513270ad --- /dev/null +++ b/apps/scalar/latest/docker-compose.yml @@ -0,0 +1,17 @@ +services: + scalar: + image: "scalarapi/api-reference:latest" + container_name: ${CONTAINER_NAME} + ports: + - "${PANEL_APP_PORT_HTTP}:8080" + volumes: + - ./data/docs:/docs:ro + labels: + createdBy: "Apps" + restart: unless-stopped + networks: + - 1panel-network + +networks: + 1panel-network: + external: true diff --git a/apps/scalar/latest/scripts/.gitkeep b/apps/scalar/latest/scripts/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/apps/scalar/latest/scripts/init.sh b/apps/scalar/latest/scripts/init.sh new file mode 100755 index 000000000..dee14f760 --- /dev/null +++ b/apps/scalar/latest/scripts/init.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" + +mkdir -p "$ROOT_DIR/data/docs" diff --git a/apps/scalar/latest/scripts/uninstall.sh b/apps/scalar/latest/scripts/uninstall.sh new file mode 100755 index 000000000..2662517fe --- /dev/null +++ b/apps/scalar/latest/scripts/uninstall.sh @@ -0,0 +1,4 @@ +#!/usr/bin/env bash +set -euo pipefail + +docker-compose down --volumes diff --git a/apps/scalar/latest/scripts/upgrade.sh b/apps/scalar/latest/scripts/upgrade.sh new file mode 100755 index 000000000..9879df4c3 --- /dev/null +++ b/apps/scalar/latest/scripts/upgrade.sh @@ -0,0 +1,3 @@ +#!/usr/bin/env bash +set -euo pipefail +exit 0 diff --git a/apps/scalar/logo.png b/apps/scalar/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..91d40a9e3d5b567278e8fc1f300137d103e85158 GIT binary patch literal 1819 zcmai#_dnZ-1I8U^wq{!Hw2pG9v&9}o8`KtO#Vjg_I7KRiGip<#xI^ry5wXP%u}bg> zF{@^;b+)3YU0>h7;C^`C&+GXIo_C^!nE^W+KN}q#9lPOEh~-Ta{~wkgZa* zZJ?(f!u^7xqvIO5vxRo$KjL!}ViBLeFN2DnFpKLj@Y5<6i`_9)q#=RreQm@l{%5ut zKh_n(xv}=@6&3*>il}bm@BV#3k)h;RdPh^w?x_ay{_**Bc}FHMs3ASbMxePoHRK4S zu&^!q(u5N|iF>1DU0FJ71r9Y9nCdSe1}|c>pgvoI{2zl<(B@HSR6^5B)o^5$<_ z&gb5n<)j340s(kY$C0GXe?ss0pF4a~T>-n<@}0%LW9xdPp&gQq)7Nm=4K~f4)+ET% ziP-0D=Z9QYww%YUG^$}`H9W=KN~##6R8fm$Qx&JHrWB~S!$5qja{*pirU|36&8;;o zNV2UIV)f2`?1LX;JkFr(STS=$t0ehL*S~ft6Z30cH2b$Qsl2U;)TyYk@X^zvO2o}~ zI7ebq38tO7&WD`Yu0o7hFS)yj!~A*nz(2_n20A=MS-hx%am*OhhcM?DVUfICa{M)? z>@kSF+*0}t-=&T;<_z0Q_W06iW^ido-pq{ddS!M!V?d>zc!c4<`E-BLAW!gns}{*--O%0XTXo&1Y4ZhJ z>G;|XxtS$C<-v`)vZzz;`J(IRp)Y(kqPoh&K+Bi9no+YS4I(Ce*GUYBi%}p6e%PcC zr5s$s>eF4W+zvgLK3-)@mRdWob>*QR;fq?kcPeaxb=fx*$~gv}mjo1ZP^zU`7J|`P z_Ksiw<;676+AQkDCANnbedQ)PD1uT}0FLLj2 zYiS)?KYDOExUe_x!Sd}sMLFx(y zXZ4a+>KtI-MAR=l8gJ)l@lW7f=D!u0bUPv7el5%QHll?k+HXA*17*j27=8zv%DXpcr9CW+$h&!vA|K) zQ_S*D^KuhvQqdMD{S>b&TnkM3@aa;b{#_NE zY90VYGR4OVETT{JPxTFa7gp#eOWjONf=Nvp5D!uiaN!o9?Lnv&coV3@!+(Lf?O8+v ztOb?^#PAVW0D|=PFfidKc zQjuuIPRt0qG)IK&y6Zod#VMu8R-ZLR?l%XzB@>!$)~Js8Ha%-w`hbm`W;ql=6@KMW zQ$r&(9cHq&np=<5?tjM{b$6*s%A_a^p@RBm>+HfxHv$^UU!Q`x;!`hL