API pública sin documentar
Clases públicas de los módulos core-* que no tienen Javadoc a nivel de tipo en el código fuente. Esta
página no inventa descripciones — es una lista de trabajo pendiente para que el equipo complete la
documentación en el código, que es donde corresponde.
31 de 110 tipos públicos (28 %) no tienen Javadoc en la declaración del tipo.
Método usado: se recorrieron todos los core-*/src/main/java/**/*.java, se localizó la declaración del tipo
público de primer nivel y se verificó si está precedida por un bloque /** … */ (saltando anotaciones
multilínea y comentarios //).
:::note "Sin Javadoc de tipo" no siempre significa "sin ninguna documentación" Varias clases de configuración documentan sus campos individualmente aunque el tipo no tenga cabecera. Están marcadas abajo — para esas, lo que falta es una línea que explique el propósito general de la clase. :::
core-auth (14)
| Tipo | Clase | Archivo |
|---|---|---|
| class | ApiKeyProperties ⚑ | core-auth/src/main/java/dev/echotechs/core/auth/apikey/ApiKeyProperties.java |
| interface | ApiKeyRepository | core-auth/src/main/java/dev/echotechs/core/auth/apikey/ApiKeyRepository.java |
| class | JwtProperties ⚑ | core-auth/src/main/java/dev/echotechs/core/auth/jwt/JwtProperties.java |
| interface | ServiceAccountClientRepository | core-auth/src/main/java/dev/echotechs/core/auth/serviceaccount/ServiceAccountClientRepository.java |
| class | RefreshTokenProperties | core-auth/src/main/java/dev/echotechs/core/auth/session/RefreshTokenProperties.java |
| interface | RefreshTokenRepository | core-auth/src/main/java/dev/echotechs/core/auth/session/RefreshTokenRepository.java |
| interface | UserSessionRepository | core-auth/src/main/java/dev/echotechs/core/auth/session/UserSessionRepository.java |
| class | AuthCookieProperties ⚑ | core-auth/src/main/java/dev/echotechs/core/auth/web/AuthCookieProperties.java |
| record | AuthenticatedUser | core-auth/src/main/java/dev/echotechs/core/auth/web/AuthenticatedUser.java |
| record | ClientCredentialsRequest | core-auth/src/main/java/dev/echotechs/core/auth/web/dto/ClientCredentialsRequest.java |
| record | LoginRequest | core-auth/src/main/java/dev/echotechs/core/auth/web/dto/LoginRequest.java |
| record | PasswordResetConfirmDto | core-auth/src/main/java/dev/echotechs/core/auth/web/dto/PasswordResetConfirmDto.java |
| record | PasswordResetRequestDto | core-auth/src/main/java/dev/echotechs/core/auth/web/dto/PasswordResetRequestDto.java |
| record | TokenResponse | core-auth/src/main/java/dev/echotechs/core/auth/web/dto/TokenResponse.java |
Los cinco DTOs de web/dto son parte del contrato HTTP público de core-auth — son los que un
generador de OpenAPI expondría, así que son los de mayor prioridad.
AuthenticatedUser es el tipo de retorno de UserCredentialAuthenticator, una de las dos interfaces que
todo proyecto de dominio tiene que implementar. Que no tenga Javadoc es notable dado que la interfaz que lo
devuelve sí lo tiene.
core-storage (6)
| Tipo | Clase | Archivo |
|---|---|---|
| record | DownloadLink | core-storage/src/main/java/dev/echotechs/core/storage/DownloadLink.java |
| record | FileDescriptor | core-storage/src/main/java/dev/echotechs/core/storage/FileDescriptor.java |
| interface | FileMetadataRepository | core-storage/src/main/java/dev/echotechs/core/storage/FileMetadataRepository.java |
| enum | FileStatus ⚑ | core-storage/src/main/java/dev/echotechs/core/storage/FileStatus.java |
| class | StorageProperties ⚑ | core-storage/src/main/java/dev/echotechs/core/storage/StorageProperties.java |
| record | InitiateUploadRequest | core-storage/src/main/java/dev/echotechs/core/storage/web/dto/InitiateUploadRequest.java |
FileDescriptor es el tipo de retorno de tres métodos públicos de FileStorageService y del controller —
vale la pena documentar por qué deliberadamente no expone bucket ni objectKey.
FileStatus documenta las tres constantes pero no el enum.
core-config (4)
| Tipo | Clase | Archivo |
|---|---|---|
| interface | ConfigEntryRepository | core-config/src/main/java/dev/echotechs/core/config/ConfigEntryRepository.java |
| class | ConfigProperties ⚑ | core-config/src/main/java/dev/echotechs/core/config/ConfigProperties.java |
| record | ConfigEntryResponse | core-config/src/main/java/dev/echotechs/core/config/web/dto/ConfigEntryResponse.java |
| record | UpdateConfigValueRequest | core-config/src/main/java/dev/echotechs/core/config/web/dto/UpdateConfigValueRequest.java |
ConfigEntryResponse tiene un campo organizationSpecific cuyo significado (si el valor es un override o
el default de plataforma) no es evidente desde el nombre.
core-notifications (2)
| Tipo | Clase | Archivo |
|---|---|---|
| enum | NotificationChannel ⚑ | core-notifications/src/main/java/dev/echotechs/core/notifications/NotificationChannel.java |
| class | NotificationProperties ⚑ | core-notifications/src/main/java/dev/echotechs/core/notifications/NotificationProperties.java |
NotificationChannel documenta bien la constante PUSH (incluido que no hay sender para ella) pero no el
enum.
core-web (2)
| Tipo | Clase | Archivo |
|---|---|---|
| class | ConflictException | core-web/src/main/java/dev/echotechs/core/web/error/ConflictException.java |
| class | ResourceNotFoundException | core-web/src/main/java/dev/echotechs/core/web/error/ResourceNotFoundException.java |
Las otras dos excepciones del paquete (ApiException, UnauthorizedException) sí tienen Javadoc, así que
la inconsistencia salta a la vista. Falta documentar el status y el code que produce cada una —
ResourceNotFoundException fija RESOURCE_NOT_FOUND, mientras ConflictException recibe el code por
parámetro.
core-authz (1)
| Tipo | Clase | Archivo |
|---|---|---|
| class | OpenFgaProperties ⚑ | core-authz/src/main/java/dev/echotechs/core/authz/OpenFgaProperties.java |
core-reporting (1)
| Tipo | Clase | Archivo |
|---|---|---|
| class | ReportGenerationException | core-reporting/src/main/java/dev/echotechs/core/reporting/ReportGenerationException.java |
Convendría documentar que no extiende ApiException, por lo que GlobalExceptionHandler la traduce a
500 y no a un 4xx.
core-workflow (1)
| Tipo | Clase | Archivo |
|---|---|---|
| interface | WorkflowTransitionRepository | core-workflow/src/main/java/dev/echotechs/core/workflow/WorkflowTransitionRepository.java |
core-persistence (0)
Sin pendientes: su único tipo público, CoreEntity, está documentado.
⚑ = el tipo no tiene Javadoc de cabecera, pero sí documenta campos o constantes individuales.
Prioridad sugerida
- DTOs de contrato HTTP (
core-auth/web/dto/*,InitiateUploadRequest,UpdateConfigValueRequest,ConfigEntryResponse) — son la superficie pública de la API y lo primero que aparecería en un OpenAPI generado. - Tipos de retorno de la API pública (
AuthenticatedUser,FileDescriptor,DownloadLink,TokenResponse) — los ve todo consumidor. - Clases
*Properties— sólo la cabecera; los campos ya están documentados en casi todas. - Repositorios — los de menor prioridad; son interfaces derivadas de Spring Data cuyos nombres de método ya se autoexplican.