Ejemplo de salida del escaneo de controladores

Ejemplo de salida del escaneo de controladores

Un ejemplo real de lo que bxSitesControllerScanDoc (Gradle) / bxsites:controller-scan (Maven) produce realmente - ver Plugin de Gradle o Plugin de Maven para saber cómo activar esto en tu propio proyecto (activado por defecto cuando la generación de OpenAPI está desactivada).

Escanea por reflexión las clases ya compiladas de tu propio proyecto en busca de controladores Spring MVC, en una JVM bifurcada, usando los tipos de anotación reales de Spring en el classpath de tu propio proyecto. Dado este controlador:

package com.example;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/books")
public class BookController {

    @GetMapping
    public String list() {
        return "[]";
    }

    @GetMapping("/{id}")
    public String getOne(@PathVariable String id) {
        return "{}";
    }

    @PostMapping
    public String create(@RequestBody String body) {
        return "{}";
    }
}

...el generador escribe api/controllers/com/example/BookController.md con este frontmatter:

---
title: "BookController"
tags: [api, controllers]
---

Y este cuerpo, reproducido abajo no como un bloque de código sino renderizado de verdad - este es el cuerpo real de la página generada, en vivo, confirmado contra esta misma clase controladora en la propia suite de pruebas del plugin:

BookController

com.example.BookController

Fíjate en que la ruta base a nivel de clase @RequestMapping("/api/books") se combina con el mapeo propio de cada método para producir la ruta completa en cada fila - composición real de rutas, no una concatenación de cadenas por conjetura. El orden de las filas viene directamente de la propia reflexión de la JVM sobre la clase compilada (no necesariamente el orden del código fuente - comportamiento real, sin retoques para este ejemplo).

Los endpoints se renderizan como una tabla de pipes de Markdown, a propósito. bx-sites da a cualquier tabla de diez filas o más su propio campo de filtrado en vivo, así que un controlador con una lista larga de endpoints obtiene búsqueda y filtrado gratis, mientras que una tabla de pipes sigue siendo legible en el Markdown en crudo, se tematiza en todas partes y entra entera en el índice de búsqueda. Las páginas de Javadoc, cuyos miembros son secciones y no filas de tabla, sí llevan la barra de chips de Alpine.js del propio generador.

Lo que esto no cubre

Alcance deliberadamente reducido, en el mismo espíritu que el generador de Javadoc: solo se reconocen las clases anotadas directamente con @Controller/@RestController (una anotación de estereotipo propia construida sobre cualquiera de las dos no se reconoce); solo se reconocen los métodos anotados directamente con @RequestMapping/@GetMapping/@PostMapping/@PutMapping/ @DeleteMapping/@PatchMapping; las clases anidadas se omiten; y como la reflexión no tiene acceso a los comentarios de documentación a nivel de código fuente, no hay texto descriptivo por endpoint como "List books" en la fila de arriba - solo el método, la ruta y la firma del manejador. Consulta las guías de Gradle/Maven enlazadas arriba para el alcance completo.