From 4132833b5d37c5104ef0eaeecdfa530dd0b49e99 Mon Sep 17 00:00:00 2001 From: Erik Michelson Date: Sun, 4 Aug 2024 14:51:52 +0200 Subject: [PATCH] refactor(api-docs): move api docs to /api/doc/ The API documentation belongs strictly to the API itself. Due to the usage of version-prefixed API endpoints, there is no conflict with existing or future endpoints. The reason behind this is that we already have enough exceptions in the routing (default everything to react-frontend, exceptions for backend) and it is hard to keep it synchronized throughout all relevant places. This came to attention as the dev setup didn't proxy the API docs to the backend. Signed-off-by: Erik Michelson --- backend/src/app-init.ts | 6 +++--- backend/src/utils/swagger.ts | 6 +++--- dev-reverse-proxy/Caddyfile | 1 - docs/content/files/setup-docker/Caddyfile | 4 ++-- docs/content/how-to/reverse-proxy.md | 7 ++----- 5 files changed, 10 insertions(+), 14 deletions(-) diff --git a/backend/src/app-init.ts b/backend/src/app-init.ts index 27b3e5ca4..fd1f35347 100644 --- a/backend/src/app-init.ts +++ b/backend/src/app-init.ts @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2022 The HedgeDoc developers (see AUTHORS file) + * SPDX-FileCopyrightText: 2024 The HedgeDoc developers (see AUTHORS file) * * SPDX-License-Identifier: AGPL-3.0-only */ @@ -31,14 +31,14 @@ export async function setupApp( ): Promise { await setupPublicApiDocs(app); logger.log( - `Serving OpenAPI docs for public API under '/apidoc/v2'`, + `Serving OpenAPI docs for public API under '/api/doc/v2'`, 'AppBootstrap', ); if (process.env.NODE_ENV === 'development') { await setupPrivateApiDocs(app); logger.log( - `Serving OpenAPI docs for private API under '/apidoc/private'`, + `Serving OpenAPI docs for private API under '/api/doc/private'`, 'AppBootstrap', ); } diff --git a/backend/src/utils/swagger.ts b/backend/src/utils/swagger.ts index ea7bc94c3..c370538cc 100644 --- a/backend/src/utils/swagger.ts +++ b/backend/src/utils/swagger.ts @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file) + * SPDX-FileCopyrightText: 2024 The HedgeDoc developers (see AUTHORS file) * * SPDX-License-Identifier: AGPL-3.0-only */ @@ -23,7 +23,7 @@ export async function setupPublicApiDocs(app: INestApplication): Promise { const publicApi = SwaggerModule.createDocument(app, publicApiOptions, { include: [PublicApiModule], }); - SwaggerModule.setup('apidoc/v2', app, publicApi); + SwaggerModule.setup('api/doc/v2', app, publicApi); } export async function setupPrivateApiDocs( @@ -38,5 +38,5 @@ export async function setupPrivateApiDocs( const privateApi = SwaggerModule.createDocument(app, privateApiOptions, { include: [PrivateApiModule], }); - SwaggerModule.setup('apidoc/private', app, privateApi); + SwaggerModule.setup('api/doc/private', app, privateApi); } diff --git a/dev-reverse-proxy/Caddyfile b/dev-reverse-proxy/Caddyfile index 0a545f8da..e43632a23 100644 --- a/dev-reverse-proxy/Caddyfile +++ b/dev-reverse-proxy/Caddyfile @@ -16,5 +16,4 @@ reverse_proxy /realtime http://localhost:{$HD_BACKEND_PORT:3000} reverse_proxy /api/* http://localhost:{$HD_BACKEND_PORT:3000} reverse_proxy /public/* http://localhost:{$HD_BACKEND_PORT:3000} reverse_proxy /uploads/* http://localhost:{$HD_BACKEND_PORT:3000} -reverse_proxy /apidoc/* http://localhost:{$HD_BACKEND_PORT:3000} reverse_proxy /* http://localhost:{$HD_FRONTEND_PORT:3001} diff --git a/docs/content/files/setup-docker/Caddyfile b/docs/content/files/setup-docker/Caddyfile index ae82699c1..67f44e9ca 100644 --- a/docs/content/files/setup-docker/Caddyfile +++ b/docs/content/files/setup-docker/Caddyfile @@ -10,5 +10,5 @@ reverse_proxy /realtime http://backend:3000 reverse_proxy /api/* http://backend:3000 reverse_proxy /public/* http://backend:3000 reverse_proxy /uploads/* http://backend:3000 -reverse_proxy /apidoc/* http://backend:3000 -reverse_proxy /* http://frontend:3001 \ No newline at end of file +reverse_proxy /media/* http://backend:3000 +reverse_proxy /* http://frontend:3001 diff --git a/docs/content/how-to/reverse-proxy.md b/docs/content/how-to/reverse-proxy.md index d4bc6c9b7..f10ba9f8c 100644 --- a/docs/content/how-to/reverse-proxy.md +++ b/docs/content/how-to/reverse-proxy.md @@ -31,7 +31,7 @@ in your `docker-compose.yml`: - hedgedoc_uploads:/usr/src/app/backend/uploads labels: traefik.enable: "true" - traefik.http.routers.hedgedoc_2_backend.rule: "Host(`md.example.com`) && PathPrefix(`/realtime`, `/api`, `/public`)" + traefik.http.routers.hedgedoc_2_backend.rule: "Host(`md.example.com`) && (PathPrefix(`/realtime`) || PathPrefix(`/api`) || PathPrefix(`/public`))" traefik.http.routers.hedgedoc_2_backend.tls: "true" traefik.http.routers.hedgedoc_2_backend.tls.certresolver: "letsencrypt" traefik.http.services.hedgedoc_2_backend.loadbalancer.server.port: "3000" @@ -113,7 +113,7 @@ Here is an example configuration for [nginx][nginx]. server { server_name md.example.com; - location ~ ^/(api|public|uploads|apidoc)/ { + location ~ ^/(api|public|uploads)/ { proxy_pass http://127.0.0.1:3000; proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Real-IP $remote_addr; @@ -168,12 +168,10 @@ Here is an example config snippet for [Apache][apache]: RewriteRule /(.*) ws://127.0.0.1:3000/$1 [P,L] ProxyPass /api http://127.0.0.1:3000/ - ProxyPass /apidoc http://127.0.0.1:3000/ ProxyPass /public http://127.0.0.1:3000/ ProxyPass /realtime http://127.0.0.1:3000/ ProxyPassReverse /api http://127.0.0.1:3000/ - ProxyPassReverse /apidoc http://127.0.0.1:3000/ ProxyPassReverse /public http://127.0.0.1:3000/ ProxyPassReverse /realtime http://127.0.0.1:3000/ @@ -202,7 +200,6 @@ Here is a list of things your reverse proxy needs to do to let HedgeDoc work: - Passing `/api/*` to - Passing `/public/*` to - Passing `/uploads/*` to -- Passing `/apidoc/*` to - Passing `/*` to - Set the `X-Forwarded-Proto` header