From 14937f3ded146ff8a2b7b81d5c61fa075e509042 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C3=ABl=20Gangloff?= Date: Tue, 2 Dec 2025 21:16:44 +0100 Subject: [PATCH] docs: add API section in the documentation --- .github/workflows/publish-docs.yml | 20 +++++ docs/.gitignore | 3 + docs/astro.config.mjs | 13 +++- docs/package.json | 3 +- docs/yarn.lock | 119 ++++++++++++++++++++++++++++- src/Entity/Instance.php | 3 +- 6 files changed, 155 insertions(+), 6 deletions(-) diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index b10b158..4f1e135 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -18,6 +18,26 @@ jobs: with: fetch-depth: 0 + - name: Set up PHP + uses: shivammathur/setup-php@v2 + with: + php-version: '8.4' + extensions: mbstring, xml, intl, curl, iconv, pdo_pgsql, sodium, zip, http + + - name: Cache Composer dependencies + uses: actions/cache@v3 + with: + path: vendor + key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }} + restore-keys: | + ${{ runner.os }}-composer- + + - name: Install dependencies + run: composer install --prefer-dist --no-progress --no-suggest --optimize-autoloader + + - name: Generate Swagger JSON + run: bin/console api:openapi:export --output=docs/swagger_docs.json + - name: Setup Node uses: actions/setup-node@v4 with: diff --git a/docs/.gitignore b/docs/.gitignore index 6240da8..976537f 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -19,3 +19,6 @@ pnpm-debug.log* # macOS-specific files .DS_Store + + +swagger_docs.json \ No newline at end of file diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index b28181a..fd57426 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -5,7 +5,10 @@ import starlightLinksValidator from 'starlight-links-validator' import mermaid from "astro-mermaid" import starlightCoolerCredit from "starlight-cooler-credit" import starlightKbd from 'starlight-kbd' +import starlightOpenAPI, {createOpenAPISidebarGroup} from 'starlight-openapi' + +const domainWatchdogSidebarGroup = createOpenAPISidebarGroup() const BASE_URL = 'https://domainwatchdog.eu' // https://astro.build/config @@ -62,9 +65,10 @@ export default defineConfig({ {label: 'Contributing', autogenerate: {directory: 'developing/contributing'}, translations: {fr: 'Contribuer'}} ], }, + {label: 'Definitions', autogenerate: {directory: 'definitions'}, collapsed: true, translations: {fr: 'Définitions'}}, + {label: 'Interoperability', items: [domainWatchdogSidebarGroup], badge: {text: 'DEV', class: 'caution'}, collapsed: true}, {label: 'Legal', autogenerate: {directory: 'legal'}, collapsed: true, translations: {fr: 'Légal'}}, {slug: 'acknowledgment', translations: {fr: 'Remerciements'}}, - {label: 'Definitions', autogenerate: {directory: 'definitions'}, collapsed: true, translations: {fr: 'Définitions'}}, ], locales: { en: { @@ -150,6 +154,13 @@ _paq.push(['enableHeartBeatTimer']); {id: 'mac', label: 'macOS'} ], }), + starlightOpenAPI([ + { + base: 'interoperability/api', + schema: 'swagger_docs.json', + sidebar: {operations: {badges: true}, group: domainWatchdogSidebarGroup} + }, + ]), ], customCss: [ './src/styles/index.css' diff --git a/docs/package.json b/docs/package.json index 78600d6..65bd6aa 100644 --- a/docs/package.json +++ b/docs/package.json @@ -24,6 +24,7 @@ "starlight-contributor-list": "^0.3.1", "starlight-cooler-credit": "^0.4.1", "starlight-kbd": "^0.2.1", - "starlight-links-validator": "^0.19.1" + "starlight-links-validator": "^0.19.1", + "starlight-openapi": "^0.21.1" } } diff --git a/docs/yarn.lock b/docs/yarn.lock index 05e972f..d185329 100644 --- a/docs/yarn.lock +++ b/docs/yarn.lock @@ -25,6 +25,14 @@ resolved "https://registry.yarnpkg.com/@antfu/utils/-/utils-9.3.0.tgz#e05e277f788ac3bec771f57a49fb64546bb32374" integrity sha512-9hFT4RauhcUzqOE4f1+frMKLZrgNog5b06I7VmZQV1BkvwvqrbC8EBZf3L1eEL2AKb6rNKjER0sEvJiSP1FXEA== +"@apidevtools/json-schema-ref-parser@^13.0.5": + version "13.0.5" + resolved "https://registry.yarnpkg.com/@apidevtools/json-schema-ref-parser/-/json-schema-ref-parser-13.0.5.tgz#e7a5cfc7df315ebcbafeb98199b72ebed9743b68" + integrity sha512-xfh4xVJD62gG6spIc7lwxoWT+l16nZu1ELyU8FkjaP/oD2yP09EvLAU6KhtudN9aML2Khhs9pY6Slr7KGTES3w== + dependencies: + "@types/json-schema" "^7.0.15" + js-yaml "^4.1.0" + "@astrojs/compiler@^2.12.2": version "2.13.0" resolved "https://registry.yarnpkg.com/@astrojs/compiler/-/compiler-2.13.0.tgz#a40bef3106fff808bd91b41680275a7e28996d63" @@ -143,12 +151,21 @@ is-wsl "^3.1.0" which-pm-runs "^1.1.0" +"@babel/code-frame@^7.22.5": + version "7.27.1" + resolved "https://registry.yarnpkg.com/@babel/code-frame/-/code-frame-7.27.1.tgz#200f715e66d52a23b221a9435534a91cc13ad5be" + integrity sha512-cjQ7ZlQ0Mv3b47hABuTevyTuYN4i+loJKGeV9flcCgIK37cCXRh+L1bd3iBHlynerhQ7BhCkn2BPbQUL+rGqFg== + dependencies: + "@babel/helper-validator-identifier" "^7.27.1" + js-tokens "^4.0.0" + picocolors "^1.1.1" + "@babel/helper-string-parser@^7.27.1": version "7.27.1" resolved "https://registry.yarnpkg.com/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz#54da796097ab19ce67ed9f88b47bb2ec49367687" integrity sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA== -"@babel/helper-validator-identifier@^7.28.5": +"@babel/helper-validator-identifier@^7.27.1", "@babel/helper-validator-identifier@^7.28.5": version "7.28.5" resolved "https://registry.yarnpkg.com/@babel/helper-validator-identifier/-/helper-validator-identifier-7.28.5.tgz#010b6938fab7cb7df74aa2bbc06aa503b8fe5fb4" integrity sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q== @@ -160,7 +177,7 @@ dependencies: "@babel/types" "^7.28.5" -"@babel/runtime@^7.23.2": +"@babel/runtime@^7.22.5", "@babel/runtime@^7.23.2": version "7.28.4" resolved "https://registry.yarnpkg.com/@babel/runtime/-/runtime-7.28.4.tgz#a70226016fabe25c5783b2f22d3e1c9bc5ca3326" integrity sha512-Q/N6JNWvIvPnLDvjlE1OUBLPQHH6l3CltCEsHIujp45zQUSSh8K+gHnaEX45yAT1nyngnINhvWtzN+Nb9D8RAQ== @@ -396,6 +413,11 @@ dependencies: "@expressive-code/core" "^0.41.3" +"@humanwhocodes/momoa@^2.0.3": + version "2.0.4" + resolved "https://registry.yarnpkg.com/@humanwhocodes/momoa/-/momoa-2.0.4.tgz#8b9e7a629651d15009c3587d07a222deeb829385" + integrity sha512-RE815I4arJFtt+FVeU1Tgp9/Xvecacji8w/V6XtXsWWH/wz/eNkNbhb+ny/+PlVZjV0rxQpRSQKNKE3lcktHEA== + "@iconify/types@^2.0.0": version "2.0.0" resolved "https://registry.yarnpkg.com/@iconify/types/-/types-2.0.0.tgz#ab0e9ea681d6c8a1214f30cd741fe3a20cc57f57" @@ -645,6 +667,35 @@ resolved "https://registry.yarnpkg.com/@pagefind/windows-x64/-/windows-x64-1.4.0.tgz#ba68fd609621132e8e314a89e2d2d52516f61723" integrity sha512-NkT+YAdgS2FPCn8mIA9bQhiBs+xmniMGq1LFPDhcFn0+2yIUEiIG06t7bsZlhdjknEQRTSdT7YitP6fC5qwP0g== +"@readme/better-ajv-errors@^2.3.2": + version "2.4.0" + resolved "https://registry.yarnpkg.com/@readme/better-ajv-errors/-/better-ajv-errors-2.4.0.tgz#96d7361e0a02644f9d58871a2fa1e0c26b7b55bf" + integrity sha512-9WODaOAKSl/mU+MYNZ2aHCrkoRSvmQ+1YkLj589OEqqjOAhbn8j7Z+ilYoiTu/he6X63/clsxxAB4qny9/dDzg== + dependencies: + "@babel/code-frame" "^7.22.5" + "@babel/runtime" "^7.22.5" + "@humanwhocodes/momoa" "^2.0.3" + jsonpointer "^5.0.0" + leven "^3.1.0" + picocolors "^1.1.1" + +"@readme/openapi-parser@^4.1.2": + version "4.1.2" + resolved "https://registry.yarnpkg.com/@readme/openapi-parser/-/openapi-parser-4.1.2.tgz#f4aeeab0b25889c2b0a972225d1db5bed136acd6" + integrity sha512-lAFH88r/CHs5VZDUocEda0OSMSQsr6801sziIjOKyVA+0hSFN+BPuelPF5XvkMROHecnPd+XEJN1iNQqCgER/g== + dependencies: + "@apidevtools/json-schema-ref-parser" "^13.0.5" + "@readme/better-ajv-errors" "^2.3.2" + "@readme/openapi-schemas" "^3.1.0" + "@types/json-schema" "^7.0.15" + ajv "^8.12.0" + ajv-draft-04 "^1.0.0" + +"@readme/openapi-schemas@^3.1.0": + version "3.1.0" + resolved "https://registry.yarnpkg.com/@readme/openapi-schemas/-/openapi-schemas-3.1.0.tgz#5ff4b704af6a8b108f9d577fd87cf73e9e7b3178" + integrity sha512-9FC/6ho8uFa8fV50+FPy/ngWN53jaUu4GRXlAjcxIRrzhltJnpKkBG2Tp0IDraFJeWrOpk84RJ9EMEEYzaI1Bw== + "@rollup/pluginutils@^5.2.0": version "5.3.0" resolved "https://registry.yarnpkg.com/@rollup/pluginutils/-/pluginutils-5.3.0.tgz#57ba1b0cbda8e7a3c597a4853c807b156e21a7b4" @@ -1078,6 +1129,11 @@ resolved "https://registry.yarnpkg.com/@types/js-yaml/-/js-yaml-4.0.9.tgz#cd82382c4f902fed9691a2ed79ec68c5898af4c2" integrity sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg== +"@types/json-schema@^7.0.15": + version "7.0.15" + resolved "https://registry.yarnpkg.com/@types/json-schema/-/json-schema-7.0.15.tgz#596a1747233694d50f6ad8a7869fcb6f56cf5841" + integrity sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA== + "@types/mdast@^4.0.0", "@types/mdast@^4.0.4": version "4.0.4" resolved "https://registry.yarnpkg.com/@types/mdast/-/mdast-4.0.4.tgz#7ccf72edd2f1aa7dd3437e180c64373585804dd6" @@ -1156,6 +1212,21 @@ acorn@^8.0.0, acorn@^8.15.0: resolved "https://registry.yarnpkg.com/acorn/-/acorn-8.15.0.tgz#a360898bc415edaac46c8241f6383975b930b816" integrity sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg== +ajv-draft-04@^1.0.0: + version "1.0.0" + resolved "https://registry.yarnpkg.com/ajv-draft-04/-/ajv-draft-04-1.0.0.tgz#3b64761b268ba0b9e668f0b41ba53fce0ad77fc8" + integrity sha512-mv00Te6nmYbRp5DCwclxtt7yV/joXJPGS7nM+97GdxvuttCOfgI3K4U25zboyeX0O+myI8ERluxQe5wljMmVIw== + +ajv@^8.12.0: + version "8.17.1" + resolved "https://registry.yarnpkg.com/ajv/-/ajv-8.17.1.tgz#37d9a5c776af6bc92d7f4f9510eba4c0a60d11a6" + integrity sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g== + dependencies: + fast-deep-equal "^3.1.3" + fast-uri "^3.0.1" + json-schema-traverse "^1.0.0" + require-from-string "^2.0.2" + ansi-align@^3.0.1: version "3.0.1" resolved "https://registry.yarnpkg.com/ansi-align/-/ansi-align-3.0.1.tgz#0cdf12e111ace773a86e9a1fad1225c43cb19a59" @@ -2123,6 +2194,11 @@ fast-deep-equal@^3.1.3: resolved "https://registry.yarnpkg.com/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz#3a7d56b559d6cbc3eb512325244e619a65c6c525" integrity sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q== +fast-uri@^3.0.1: + version "3.1.0" + resolved "https://registry.yarnpkg.com/fast-uri/-/fast-uri-3.1.0.tgz#66eecff6c764c0df9b762e62ca7edcfb53b4edfa" + integrity sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA== + fdir@^6.4.4, fdir@^6.5.0: version "6.5.0" resolved "https://registry.yarnpkg.com/fdir/-/fdir-6.5.0.tgz#ed2ab967a331ade62f18d077dae192684d50d350" @@ -2606,6 +2682,11 @@ is-wsl@^3.1.0: dependencies: is-inside-container "^1.0.0" +js-tokens@^4.0.0: + version "4.0.0" + resolved "https://registry.yarnpkg.com/js-tokens/-/js-tokens-4.0.0.tgz#19203fb59991df98e3a287050d4647cdeaf32499" + integrity sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ== + js-yaml@^4.1.0: version "4.1.0" resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-4.1.0.tgz#c1fb65f8f5017901cdd2c951864ba18458a10602" @@ -2618,6 +2699,16 @@ json-buffer@3.0.1: resolved "https://registry.yarnpkg.com/json-buffer/-/json-buffer-3.0.1.tgz#9338802a30d3b6605fbe0613e094008ca8c05a13" integrity sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ== +json-schema-traverse@^1.0.0: + version "1.0.0" + resolved "https://registry.yarnpkg.com/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz#ae7bcb3656ab77a73ba5c49bf654f38e6b6860e2" + integrity sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug== + +jsonpointer@^5.0.0: + version "5.0.1" + resolved "https://registry.yarnpkg.com/jsonpointer/-/jsonpointer-5.0.1.tgz#2110e0af0900fd37467b5907ecd13a7884a1b559" + integrity sha512-p/nXbhSEcu3pZRdkW1OfJhpsVtW1gd4Wa1fnQc9YLiTfAjn0312eMKimbdIQzuZl9aa9xUGaRlP9T/CJE/ditQ== + katex@^0.16.22: version "0.16.25" resolved "https://registry.yarnpkg.com/katex/-/katex-0.16.25.tgz#61699984277e3bdb3e89e0e446b83cd0a57d87db" @@ -2678,6 +2769,11 @@ layout-base@^2.0.0: resolved "https://registry.yarnpkg.com/layout-base/-/layout-base-2.0.1.tgz#d0337913586c90f9c2c075292069f5c2da5dd285" integrity sha512-dp3s92+uNI1hWIpPGH3jK2kxE2lMjdXdr+DH8ynZHpd6PUlH6x6cbuXnoMmiNumznqaNO31xu9e79F0uuZ0JFg== +leven@^3.1.0: + version "3.1.0" + resolved "https://registry.yarnpkg.com/leven/-/leven-3.1.0.tgz#77891de834064cccba82ae7842bb6b14a13ed7f2" + integrity sha512-qsda+H8jTaUaN/x5vzW2rzc+8Rw4TAQ/4KjB46IwK5VH+IlVeeeje/EoZRpiXvIqjFgK84QffqPztGI3VBLG1A== + local-pkg@^1.1.1: version "1.1.2" resolved "https://registry.yarnpkg.com/local-pkg/-/local-pkg-1.1.2.tgz#c03d208787126445303f8161619dc701afa4abb5" @@ -3874,6 +3970,11 @@ remark-stringify@^11.0.0: mdast-util-to-markdown "^2.0.0" unified "^11.0.0" +require-from-string@^2.0.2: + version "2.0.2" + resolved "https://registry.yarnpkg.com/require-from-string/-/require-from-string-2.0.2.tgz#89a7fdd938261267318eafe14f9c32e598c36909" + integrity sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw== + restructure@^3.0.0: version "3.0.2" resolved "https://registry.yarnpkg.com/restructure/-/restructure-3.0.2.tgz#e6b2fad214f78edee21797fa8160fef50eb9b49a" @@ -4108,6 +4209,15 @@ starlight-links-validator@^0.19.1: terminal-link "^5.0.0" unist-util-visit "^5.0.0" +starlight-openapi@^0.21.1: + version "0.21.1" + resolved "https://registry.yarnpkg.com/starlight-openapi/-/starlight-openapi-0.21.1.tgz#29895ab77d3fd5ad77fd595a60b30381572bcb47" + integrity sha512-hHefUWQuLz26Fc8B0XOrdxOnOmJkKzyAssqEfDSZTC76GH05eT5/fCuJ76lq9N3uEjHmCKb6vWPlr7EbLbJQEg== + dependencies: + "@readme/openapi-parser" "^4.1.2" + github-slugger "^2.0.0" + url-template "^3.1.1" + stream-replace-string@^2.0.0: version "2.0.0" resolved "https://registry.yarnpkg.com/stream-replace-string/-/stream-replace-string-2.0.0.tgz#e49fd584bd1c633613e010bc73b9db49cb5024ad" @@ -4394,6 +4504,11 @@ unstorage@^1.17.0: ofetch "^1.5.0" ufo "^1.6.1" +url-template@^3.1.1: + version "3.1.1" + resolved "https://registry.yarnpkg.com/url-template/-/url-template-3.1.1.tgz#c220d5f3f793d28b0de341002112879cc8a43905" + integrity sha512-4oszoaEKE/mQOtAmdMWqIRHmkxWkUZMnXFnjQ5i01CuRSK3uluxcH1MRVVVWmhlnzT1SCDfKxxficm2G37qzCA== + util-deprecate@^1.0.2: version "1.0.2" resolved "https://registry.yarnpkg.com/util-deprecate/-/util-deprecate-1.0.2.tgz#450d4dc9fa70de732762fbd2d4a28981419a0ccf" diff --git a/src/Entity/Instance.php b/src/Entity/Instance.php index f704d1c..d2c94be 100644 --- a/src/Entity/Instance.php +++ b/src/Entity/Instance.php @@ -13,8 +13,7 @@ use App\Controller\InstanceController; controller: InstanceController::class, shortName: 'Configuration', description: 'Public configuration of the server', - read: false, - name: 'server-configuration', + read: false ), ] )]