Генерация API-документации из аннотаций!

Когда API растёт, документация быстро устаревает. Решение простое, хранить описание рядом с методами в аннотациях и генерировать доку автоматически.

Создаём аннотацию для эндпоинтов:

@java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.RUNTIME)
@java.lang.annotation.Target(java.lang.annotation.ElementType.METHOD)
@interface ApiRoute {
  String method();
  String path();
  String desc() default "";
}

Помечаем методы аннотацией:

@ApiRoute(method = "GET", path = "/health", desc = "Проверка статуса сервиса")
void health() {}

@ApiRoute(method = "POST", path = "/login", desc = "Логин по паролю")
void login() {}

Сканируем методы через reflection и собираем Markdown:

var sb = new StringBuilder("# API\n\n");
for (var m : MyApi.class.getDeclaredMethods()) {
  var a = m.getAnnotation(ApiRoute.class);
  if (a == null) continue;
  sb.append("- **").append(a.method()).append(" ").append(a.path()).append("**\n")
    .append("  ").append(a.desc()).append("\n\n");
}

Сохраняем документацию в файл:

java.nio.file.Files.writeString(
    java.nio.file.Path.of("API.md"),
    sb.toString()
);

В итоге API,md генерится из кода и всегда соответствует реальным эндпоинтам.

👉 Java Ready | #практика