Fix: Swagger UI/OpenAPI под префиксом /pdf-converter, документация открыта без ключа #4

Merged
pjandro merged 1 commits from fix/swagger-ui-base-path into main 2026-10-16 00:17:04 +03:00
Collaborator

Проблема

На проде https://pjandro.ru/pdf-converter/ пути до OpenAPI/Swagger UI битые: наружный nginx срезает префикс, а springdoc генерирует абсолютные URL от корня хоста. Плюс ApiKeyFilter давал 401 на документацию — браузер ключ в заголовок положить не может.

Изменения

  • server.forward-headers-strategy=framework + springdoc.swagger-ui.persist-authorization=true — server спека https://pjandro.ru/pdf-converter, configUrl с префиксом (проверено на jar с X-Forwarded-*). native-клапан Tomcat X-Forwarded-Prefix не понимает.
  • ApiKeyFilter: матч по пути без forwarded-contextPath (иначе под префиксным заголовком /actuator/health → 401 и Docker HEALTHCHECK умрёт) + открытые без ключа /swagger-ui*, /v3/api-docs*; /api/** под ключом как раньше.
  • OpenApiConfig: @SecurityScheme X-API-Key → кнопка Authorize; @SecurityRequirement на convert → «Try it out» шлёт ключ.
  • Тесты: удалён openApiRequiresKey (пинил старую политику), добавлены docsOpenWithoutKey, forwardedPrefix_healthStaysOpen, forwardedPrefix_docsOpenWithoutKey.
  • AGENTS.md синхронизирован (открытая документация, 10 классов app, 126 @Test, X-Forwarded-* наружного nginx, канонический URL документации).

Проверка

mvn clean verify — BUILD SUCCESS (core 104 + app 22). Смоук на java -jar с ключом и X-Forwarded-Prefix/Proto/Host: health 200 без ключа, /v3/api-docs server https://pjandro.ru/pdf-converter + схема ApiKey, /swagger-ui.html → 302 с префиксом, configUrl /pdf-converter/v3/api-docs/swagger-config, convert без ключа 401 / с ключом 200 %PDF; без префиксных заголовков — корректные корневые URL.

После мержа (вне репо)

Наружному nginx прод-хоста добавить в location /pdf-converter/: proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Prefix /pdf-converter;; из прод-compose убрать env-ы SPRINGDOC_*_ENABLED=false; restart.sh --build (детали в DEPLOY.md).

## Проблема На проде `https://pjandro.ru/pdf-converter/` пути до OpenAPI/Swagger UI битые: наружный nginx срезает префикс, а springdoc генерирует абсолютные URL от корня хоста. Плюс `ApiKeyFilter` давал 401 на документацию — браузер ключ в заголовок положить не может. ## Изменения - `server.forward-headers-strategy=framework` + `springdoc.swagger-ui.persist-authorization=true` — server спека `https://pjandro.ru/pdf-converter`, configUrl с префиксом (проверено на jar с `X-Forwarded-*`). `native`-клапан Tomcat `X-Forwarded-Prefix` не понимает. - `ApiKeyFilter`: матч по пути **без forwarded-contextPath** (иначе под префиксным заголовком `/actuator/health` → 401 и Docker HEALTHCHECK умрёт) + открытые без ключа `/swagger-ui*`, `/v3/api-docs*`; `/api/**` под ключом как раньше. - `OpenApiConfig`: `@SecurityScheme` X-API-Key → кнопка Authorize; `@SecurityRequirement` на `convert` → «Try it out» шлёт ключ. - Тесты: удалён `openApiRequiresKey` (пинил старую политику), добавлены `docsOpenWithoutKey`, `forwardedPrefix_healthStaysOpen`, `forwardedPrefix_docsOpenWithoutKey`. - AGENTS.md синхронизирован (открытая документация, 10 классов app, 126 @Test, X-Forwarded-* наружного nginx, канонический URL документации). ## Проверка `mvn clean verify` — BUILD SUCCESS (core 104 + app 22). Смоук на `java -jar` с ключом и `X-Forwarded-Prefix/Proto/Host`: health 200 без ключа, `/v3/api-docs` server `https://pjandro.ru/pdf-converter` + схема `ApiKey`, `/swagger-ui.html` → 302 с префиксом, configUrl `/pdf-converter/v3/api-docs/swagger-config`, convert без ключа 401 / с ключом 200 `%PDF`; без префиксных заголовков — корректные корневые URL. ## После мержа (вне репо) Наружному nginx прод-хоста добавить в `location /pdf-converter/`: `proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Prefix /pdf-converter;`; из прод-compose убрать env-ы `SPRINGDOC_*_ENABLED=false`; `restart.sh --build` (детали в DEPLOY.md).
ai added 1 commit 2026-10-16 00:14:29 +03:00
Прод (наружный nginx срезает /pdf-converter/): springdoc генерировал
абсолютные URL от корня хоста — пути до /v3/api-docs и swagger-ui битые.
server.forward-headers-strategy=framework + X-Forwarded-* (добавляет
наружный nginx) дают server https://pjandro.ru/pdf-converter и configUrl
с префиксом; 'native'-клапан Tomcat X-Forwarded-Prefix не понимает.

ApiKeyFilter: матч по пути без forwarded-contextPath (под префиксным
заголовком getRequestURI() включает префикс — HEALTHCHECK получил бы 401)
+ открытые без ключа /swagger-ui* и /v3/api-docs* (браузер не может
положить ключ в заголовок при загрузке UI; /api/** под ключом).
OpenApiConfig: @SecurityScheme X-API-Key — кнопка Authorize в UI,
@SecurityRequirement на convert — «Try it out» с ключом.
springdoc.swagger-ui.persist-authorization=true.

Регрессии: ApiKeyFilterTest#docsOpenWithoutKey,
#forwardedPrefix_healthStaysOpen, #forwardedPrefix_docsOpenWithoutKey
(вместо удалённого openApiRequiresKey). AGENTS.md синхронизирован.
pjandro merged commit 5ef4fa1a22 into main 2026-10-16 00:17:04 +03:00
Sign in to join this conversation.
No Reviewers
No Label
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: pjandro/java-word-pdf#4