github/hedgedoc
1
0
Fork 0
mirror of https://github.com/hedgedoc/hedgedoc.git synced 2024-11-21 17:26:29 -05:00
Code Issues Projects Releases Packages Wiki Activity

refactor(api-docs): move api docs to /api/doc/

Browse source 
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>
This commit is contained in:
Erik Michelson 2024-08-04 14:51:52 +02:00 committed by Philip Molares
parent 7f665fae4b
commit 4132833b5d
5 changed files with 10 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
backend/src/app-init.ts
View file

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

6
backend/src/utils/swagger.ts
View file

@ -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);
}

1
dev-reverse-proxy/Caddyfile
View file

@ -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}

2
docs/content/files/setup-docker/Caddyfile
View file

@ -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

7
docs/content/how-to/reverse-proxy.md
View file

@ -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