Documenter efficacement

public String generateRandomPassword() {
    /* TODO: keep this in sync with the security requirements */
    String UPPER = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
    String LOWER = "abcdefghijklmnopqrstuvwxyz";
    String DIGITS = "0123456789";
    String SYMBOLS = "!@#$%&*";
    String ALL_CHARS = UPPER + LOWER + DIGITS + SYMBOLS;

    /* Generate the password char by char while ensuring every
       char category is represented */
    StringBuilder password = new StringBuilder(32);
    /* Using a SecureRandom is required to avoid attacker
       guessing the generated password */
    SecureRandom random = new SecureRandom();
    for (int i = 0; i < 32; i++) {
        int idx = random.nextInt(ALL_CHARS.length());
        password.append(ALL_CHARS.charAt(idx));
    }
    return password.toString();
}

public String generateRandomPassword() {
    /* ✅ TODO: keep this in sync with the security requirements */
    String UPPER = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
    String LOWER = "abcdefghijklmnopqrstuvwxyz";
    String DIGITS = "0123456789";
    String SYMBOLS = "!@#$%&*";
    String ALL_CHARS = UPPER + LOWER + DIGITS + SYMBOLS;

    /* ❌💀 Generate the password char by char while ensuring every
       char category is represented */
    StringBuilder password = new StringBuilder(32);
    /* ✅ Using a SecureRandom is required to avoid attacker
       guessing the generated password */
    SecureRandom random = new SecureRandom();
    for (int i = 0; i < 32; i++) {
        int idx = random.nextInt(ALL_CHARS.length());
        password.append(ALL_CHARS.charAt(idx));
    }
    return password.toString();
}

@SuppressWarnings("unused") // Fix false positive by Sonar (used by Spring)
@Configuration
public class DatabaseConfiguration {
    @Bean
    public DataSource datasource() {
        /* ... */
    }

    private DatabaseConfiguration() {
        // This class should not be instantiated manually,
        // it is managed by Spring
    }
}

/**
 * Connecteur de base de données de la suite d'outils Imaginary
 * @see <a href="https://libs.imaginary.com">Imaginary Website</a>
 */
public class ImaginaryDB implements AutoCloseable {

    /**
     * Chemin vers le fichier de configuration par défaut
     */
    public static final String DEFAULT_CONFIGURATION_FILE =
        "src/main/resources/imaginary-db.properties";

/**
 * Crée une nouvelle instance automatiquement configurée
 * via le fichier par défaut
 *
 * @return La nouvelle instance
 * @throws java.lang.RuntimeException Si le fichier par défaut est absent
 * {@link ImaginaryDB#DEFAULT_CONFIGURATION_FILE}
 */
public static ImaginaryDB getInstance() {
    // ...
}

/**
 * Exécute une requête modification
 * <p>
 * La requête peut comporter des paramètres, via l'utilisation
 * du caractère <code>?</code> :
 * <pre>execute("UPDATE my_table SET foo = '?'", "bar")</pre>
 * </p>
 *
 * @param sql    La requête SQL
 * @param params Les paramètres de la requête, si nécessaire
 * @return Le nombre de lignes impactées
 * @throws SQLException En cas d'erreur lors de l'exécution de la requête
 */
public int execute(String sql, Object... params) throws SQLException {
    // ...
}

@OpenApi(
    tags = {"Grimoire Club"},
    summary = "Add a sorcerer into the club",
    path = "/clubs/{id}/members",
    methods = POST,
    pathParams = {
        @OpenApiParam(name = "id", required = true, description = "Club ID"),
    },
    requestBody = @OpenApiRequestBody(
        content = @OpenApiContent(from = AddMemberDto.class)
    )
    // ...
)
public void addMember(Context ctx) { /* ... */ }

/**
 * @api [post] /clubs/{id}/members
 * tags:
 *   - Grimoire Club
 * summary: Add a sorcerer into the club
 * parameters:
 *   - name: id
 *     in: path
 *     description: Club ID
 *     required: true
 *     schema:
 *       type: string
 * requestBody:
 *   ...
 */
public void addMember(Context ctx) { /* ... */ }

type(optional scope): description

optional body
can be multiline !

Feature: Authentification

  Scenario: Connexion avec un mot de passe valide
    Given John et son mot de passe '5RziLh2w'
    When il saisit ses identifiants
    Then il est redirigé vers son tableau de bord

public class AuthentificationSteps {
    private String login;
    private String password;
    private Response response;

    @Given("{word} et son mot de passe '{word}'")
    public void existing_user_with_password(String login, String password) {
        this.login = login;
        this.password = password;
    }

    @When("il saisit ses identifiants")
    public void il_saisit_ses_identifiants() {
        this.reponse = authentificationService.authenticate(login, password);
    }

    @Then("il est redirigé vers son tableau de bord")
    public void il_est_redirige_vers_son_tableau_de_bord() {
        assertThat(reponse.getRedirectPath()).isEqualTo("/dashboard");
    }
}

# Authentication
## Connexion avec un mot de passe valide

Lorsque [John](- "#login") utilise son mot de passe '[5RziLh2w](- "#password")'
[pour se connecter](- "#response = authenticate(#login, #password)"),
il est [redirigé vers son tableau de bord](- "c:assertTrue=isDashboard(#response)")

public class AuthenticationFixture {

    private String login;
    private String password;

    public void setLogin(String login) {
        this.login = login;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public Response authenticate(String login, String password) {
        return authenticationService.authenticate(login, password);
    }

    public boolean isDashboard(Response response) {
        return "/dashboard".equals(response.getRedirectPath());
    }
}