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 <github@erik.michelson.eu>

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<void> {
   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',
     );
   }

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<void> {
   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);
 }

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}

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 /media/* http://backend:3000
-reverse_proxy /* http://frontend:3001
+reverse_proxy /* http://frontend:3001

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 <http://localhost:3000>
 - Passing `/public/*` to <http://localhost:3000>
 - Passing `/uploads/*` to <http://localhost:3000>
-- Passing `/apidoc/*` to <http://localhost:3000>
 - Passing `/*` to <http://localhost:3001>
 - Set the `X-Forwarded-Proto` header