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

Прод (наружный 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 синхронизирован.
This commit is contained in:
Pjandro
2026-10-15 21:13:42 +00:00
parent 05e3789358
commit c7dec86b54
7 changed files with 92 additions and 16 deletions
+1 -1
View File
@@ -41,7 +41,7 @@
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
</dependency>
<!-- /actuator/health — open-эндпоинт для Docker HEALTHCHECK (swagger в проде выключен) -->
<!-- /actuator/health — open-эндпоинт для Docker HEALTHCHECK -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
@@ -15,17 +15,24 @@ import java.security.MessageDigest;
/**
* Единственная граница доступа: заголовок {@value #HEADER} обязан совпадать с
* {@code wordpdf.api-key}. Пустое свойство = фильтрация выключена (dev/тесты).
* {@code /actuator/**} открыт — им дышит Docker HEALTHCHECK. Ответ 401 пишется
* здесь же, {@link ApiExceptionHandler} ошибок фильтров не видит; форма тела —
* Наружу без ключа открыты {@code /actuator/**} (им дышит Docker HEALTHCHECK)
* и документация springdoc ({@code /swagger-ui*}, {@code /v3/api-docs*}) —
* браузер не может положить ключ в заголовок при загрузке UI; ключ обязателен
* для всего остального (фактически {@code /api/**}). Ответ 401 пишется здесь же,
* {@link ApiExceptionHandler} ошибок фильтров не видит; форма тела —
* та же {@code {"error": …}}.
*
* <p>Регрессия — ApiKeyFilterTest.</p>
* <p>Регрессии — ApiKeyFilterTest#forwardedPrefix_healthStaysOpen,
* ApiKeyFilterTest#docsOpenWithoutKey.</p>
*/
@Component
final class ApiKeyFilter extends OncePerRequestFilter {
static final String HEADER = "X-API-Key";
/** Открытые пути без ключа: actuator (Docker HEALTHCHECK) и springdoc-документация. */
private static final String[] OPEN_PREFIXES = {"/actuator/", "/swagger-ui", "/v3/api-docs"};
/** null — аутентификация выключена. */
private final byte[] expected;
@@ -37,7 +44,7 @@ final class ApiKeyFilter extends OncePerRequestFilter {
@Override
protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
FilterChain chain) throws ServletException, IOException {
if (expected == null || request.getRequestURI().startsWith("/actuator/")) {
if (expected == null || isOpen(path(request))) {
chain.doFilter(request, response);
return;
}
@@ -54,4 +61,23 @@ final class ApiKeyFilter extends OncePerRequestFilter {
response.getWriter().write(
"{\"error\":\"Ключ доступа не передан или неверен (заголовок X-API-Key)\"}");
}
/**
* Путь приложения без forwarded-префикса: при
* server.forward-headers-strategy=framework заголовок X-Forwarded-Prefix
* становится contextPath, и getRequestURI() возвращает URI уже с ним —
* матч по сырому URI теряет /actuator/ (Docker HEALTHCHECK получил бы 401).
*/
private static String path(HttpServletRequest request) {
return request.getRequestURI().substring(request.getContextPath().length());
}
private static boolean isOpen(String path) {
for (String prefix : OPEN_PREFIXES) {
if (path.startsWith(prefix)) {
return true;
}
}
return false;
}
}
@@ -1,6 +1,7 @@
package ru.pjandro.wordpdf.app;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import org.springframework.http.ContentDisposition;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
@@ -60,6 +61,7 @@ final class ConvertController {
description = "renderCharts/renderSmartArt — факультативно, по умолчанию настройки ядра; "
+ "лимиты входа (размер/страницы) задаёт только конфигурация сервера "
+ "(свойства wordpdf.max-bytes/wordpdf.max-pages), параметрами запроса не переопределяются")
@SecurityRequirement(name = OpenApiConfig.SCHEME)
@PostMapping(
path = "/api/v1/convert",
consumes = MediaType.MULTIPART_FORM_DATA_VALUE,
@@ -0,0 +1,22 @@
package ru.pjandro.wordpdf.app;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeIn;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import org.springframework.context.annotation.Configuration;
/**
* Схема доступа X-API-Key для springdoc: без неё Swagger UI не показывает
* Authorize и «Try it out» слал бы запросы без ключа (401). Документация
* наружу открыта (ApiKeyFilter), секрет — сам ключ, он в спеке не хранится.
*/
@Configuration(proxyBeanMethods = false)
@SecurityScheme(
name = OpenApiConfig.SCHEME,
type = SecuritySchemeType.APIKEY,
paramName = ApiKeyFilter.HEADER,
description = "Ключ доступа (свойство сервера wordpdf.api-key, прод — env WORDPDF_API_KEY)")
class OpenApiConfig {
static final String SCHEME = "ApiKey";
}
@@ -17,3 +17,11 @@ wordpdf.convert-timeout=2m
# Ключ доступа (заголовок X-API-Key). Пусто = аутентификация выключена
# (dev: java -jar / тесты). В docker-compose задан ${WORDPDF_API_KEY:?} — fail-closed.
wordpdf.api-key=
# Работа за префикс-срезающим прокси (прод: наружный nginx срезает
# /pdf-converter/): ForwardedHeaderFilter восстанавливает схему/хост/префикс из
# X-Forwarded-*, springdoc генерирует swagger-config и server спека с префиксом.
# 'native' (клапан Tomcat) X-Forwarded-Prefix не понимает — только 'framework'.
server.forward-headers-strategy=framework
# Swagger UI: не требовать ключ заново после перезагрузки страницы
springdoc.swagger-ui.persist-authorization=true
@@ -88,10 +88,28 @@ class ApiKeyFilterTest {
}
@Test
void openApiRequiresKey() throws Exception {
// в тестах springdoc включён; в проде выключен env'ом — фильтр
// накрывает документацию, когда она активна
void docsOpenWithoutKey() throws Exception {
// документация наружу открыта без ключа (браузер не может положить
// ключ в заголовок при загрузке UI); в тестах springdoc включён
mockMvc.perform(get("/v3/api-docs"))
.andExpect(status().isUnauthorized());
.andExpect(status().isOk())
.andExpect(jsonPath("$.components.securitySchemes.ApiKey.type").value("apiKey"))
.andExpect(jsonPath("$.components.securitySchemes.ApiKey.name").value("X-API-Key"));
mockMvc.perform(get("/swagger-ui/index.html"))
.andExpect(status().isOk());
}
@Test
void forwardedPrefix_healthStaysOpen() throws Exception {
// X-Forwarded-Prefix переезжает в contextPath, getRequestURI() — с префиксом;
// без отсечения contextPath в фильтре HEALTHCHECK получил бы 401
mockMvc.perform(get("/actuator/health").header("X-Forwarded-Prefix", "/pdf-converter"))
.andExpect(status().isOk());
}
@Test
void forwardedPrefix_docsOpenWithoutKey() throws Exception {
mockMvc.perform(get("/v3/api-docs").header("X-Forwarded-Prefix", "/pdf-converter"))
.andExpect(status().isOk());
}
}