From b3bfb7e267051a428f0d3022213a01fa4ba50f3d Mon Sep 17 00:00:00 2001 From: Thibaut Valentin Date: Fri, 19 Jul 2024 23:30:38 +0200 Subject: [PATCH] wip: swagger p3 --- .../ffsaf/data/model/AffiliationModel.java | 3 + .../ffsaf/data/model/ClubModel.java | 19 ++++++- .../titionfire/ffsaf/rest/AssoEndpoints.java | 15 +---- .../ffsaf/rest/data/DeskMember.java | 6 ++ .../ffsaf/rest/data/SimpleReqAffiliation.java | 6 ++ .../rest/from/AffiliationRequestForm.java | 41 +++++++++++++ .../rest/from/AffiliationRequestSaveForm.java | 57 ++++++++++++++++++- .../ffsaf/rest/from/ClubMemberForm.java | 11 ++++ .../ffsaf/rest/from/FullClubForm.java | 15 +++++ 9 files changed, 157 insertions(+), 16 deletions(-) diff --git a/src/main/java/fr/titionfire/ffsaf/data/model/AffiliationModel.java b/src/main/java/fr/titionfire/ffsaf/data/model/AffiliationModel.java index d3d0dfd..96688bb 100644 --- a/src/main/java/fr/titionfire/ffsaf/data/model/AffiliationModel.java +++ b/src/main/java/fr/titionfire/ffsaf/data/model/AffiliationModel.java @@ -3,6 +3,7 @@ package fr.titionfire.ffsaf.data.model; import io.quarkus.runtime.annotations.RegisterForReflection; import jakarta.persistence.*; import lombok.*; +import org.eclipse.microprofile.openapi.annotations.media.Schema; @Getter @Setter @@ -16,11 +17,13 @@ import lombok.*; public class AffiliationModel { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) + @Schema(description = "Identifiant de l'affiliation", example = "42") Long id; @ManyToOne(fetch = FetchType.EAGER) @JoinColumn(name = "club", referencedColumnName = "id") ClubModel club; + @Schema(description = "Saison de l'affiliation", example = "2021") int saison; } diff --git a/src/main/java/fr/titionfire/ffsaf/data/model/ClubModel.java b/src/main/java/fr/titionfire/ffsaf/data/model/ClubModel.java index 72a30de..e69b1fc 100644 --- a/src/main/java/fr/titionfire/ffsaf/data/model/ClubModel.java +++ b/src/main/java/fr/titionfire/ffsaf/data/model/ClubModel.java @@ -4,6 +4,7 @@ import fr.titionfire.ffsaf.utils.Contact; import io.quarkus.runtime.annotations.RegisterForReflection; import jakarta.persistence.*; import lombok.*; +import org.eclipse.microprofile.openapi.annotations.media.Schema; import java.util.List; import java.util.Map; @@ -20,12 +21,16 @@ import java.util.Map; public class ClubModel { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) + @Schema(description = "Identifiant du club", example = "1") Long id; + @Schema(description = "Identifiant long du club (UUID)", example = "b94f3167-3f6a-449c-a73b-ec84202bf07e") String clubId; + @Schema(description = "Nom du club", example = "Association sportive") String name; + @Schema(description = "Pays du club", example = "FR") String country; //@Enumerated(EnumType.STRING) @@ -33,28 +38,38 @@ public class ClubModel { @CollectionTable(name = "club_contact_mapping", joinColumns = {@JoinColumn(name = "club_id", referencedColumnName = "id")}) @MapKeyColumn(name = "contact_type") + @Schema(description = "Les contacts du club", example = "{\"SITE\": \"www.test.com\", \"COURRIEL\": \"test@test.com\"}") Map contact; @Lob - @Column(length=4096) + @Column(length = 4096) + @Schema(description = "Liste des lieux d'entraînement", example = "[{\"text\":\"addr 1\",\"lng\":2.24654,\"lat\":52.4868658},{\"text\":\"addr 2\",\"lng\":2.88654,\"lat\":52.7865456}]") String training_location; @Lob - @Column(length=4096) + @Column(length = 4096) + @Schema(description = "Liste des jours et horaires d'entraînement (jours 0-6, 0=>lundi) (temps en minute depuis 00:00, 122=>2h02)", example = "[{\"day\":0,\"time_start\":164,\"time_end\":240},{\"day\":3,\"time_start\":124,\"time_end\":250}]") String training_day_time; + @Schema(description = "Contact interne du club", example = "john.doe@test.com") String contact_intern; + @Schema(description = "Adresse postale du club", example = "1 rue de l'exemple, 75000 Paris") String address; + @Schema(description = "RNA du club", example = "W123456789") String RNA; + @Schema(description = "Numéro SIRET du club", example = "12345678901234") Long SIRET; + @Schema(description = "Numéro d'affiliation du club", example = "12345") Long no_affiliation; + @Schema(description = "Club international", example = "false") boolean international; @OneToMany(mappedBy = "club", fetch = FetchType.LAZY, cascade = CascadeType.ALL) + @Schema(description = "Liste des affiliations du club (optionnel)") List affiliations; } diff --git a/src/main/java/fr/titionfire/ffsaf/rest/AssoEndpoints.java b/src/main/java/fr/titionfire/ffsaf/rest/AssoEndpoints.java index 7fec841..a7904c5 100644 --- a/src/main/java/fr/titionfire/ffsaf/rest/AssoEndpoints.java +++ b/src/main/java/fr/titionfire/ffsaf/rest/AssoEndpoints.java @@ -7,13 +7,8 @@ import io.smallrye.mutiny.Uni; import jakarta.ws.rs.*; import jakarta.ws.rs.core.MediaType; import org.eclipse.microprofile.openapi.annotations.Operation; -import org.eclipse.microprofile.openapi.annotations.parameters.Parameter; -import org.eclipse.microprofile.openapi.annotations.responses.APIResponse; -import org.eclipse.microprofile.openapi.annotations.responses.APIResponses; -import org.eclipse.microprofile.openapi.annotations.tags.Tag; import org.eclipse.microprofile.rest.client.inject.RestClient; -@Tag(name = "Association", description = "Récupération des informations d'une association depuis la base de données Française") @Path("api/asso") public class AssoEndpoints { @@ -23,14 +18,8 @@ public class AssoEndpoints { @GET @Path("siren/{siren}") @Produces(MediaType.APPLICATION_JSON) - @Operation(summary = "Renvoie les informations d'une association à partir de son numéro SIREN", - description = "Cette méthode renvoie les informations d'une association à partir de son numéro SIREN.") - @APIResponses(value = { - @APIResponse(responseCode = "200", description = "Réussite"), - @APIResponse(responseCode = "404", description = "Numéro SIREN introuvable") - }) - public Uni getInfoSiren( - @Parameter(description = "Le numéro SIREN de l'association à récupérer") @PathParam("siren") String siren) { + @Operation(hidden = true) + public Uni getInfoSiren(@PathParam("siren") String siren) { return sirenService.get_unite(siren).onFailure().transform(throwable -> { if (throwable instanceof WebApplicationException exception) { if (exception.getResponse().getStatus() == 400) diff --git a/src/main/java/fr/titionfire/ffsaf/rest/data/DeskMember.java b/src/main/java/fr/titionfire/ffsaf/rest/data/DeskMember.java index c653916..7bffcfc 100644 --- a/src/main/java/fr/titionfire/ffsaf/rest/data/DeskMember.java +++ b/src/main/java/fr/titionfire/ffsaf/rest/data/DeskMember.java @@ -4,14 +4,20 @@ import fr.titionfire.ffsaf.data.model.MembreModel; import io.quarkus.runtime.annotations.RegisterForReflection; import lombok.Data; import lombok.NoArgsConstructor; +import org.eclipse.microprofile.openapi.annotations.media.Schema; @Data @NoArgsConstructor @RegisterForReflection +@Schema(name = "BureauMembre") public class DeskMember { + @Schema(description = "Identifiant du membre", example = "1") private Long id; + @Schema(description = "Nom du membre", example = "Doe") private String lname; + @Schema(description = "Prénom du membre", example = "John") private String fname; + @Schema(description = "Rôle du membre", example = "Président") private String role; public static DeskMember fromModel(MembreModel membreModel) { diff --git a/src/main/java/fr/titionfire/ffsaf/rest/data/SimpleReqAffiliation.java b/src/main/java/fr/titionfire/ffsaf/rest/data/SimpleReqAffiliation.java index 9b0a594..4f2b016 100644 --- a/src/main/java/fr/titionfire/ffsaf/rest/data/SimpleReqAffiliation.java +++ b/src/main/java/fr/titionfire/ffsaf/rest/data/SimpleReqAffiliation.java @@ -6,6 +6,7 @@ import io.quarkus.runtime.annotations.RegisterForReflection; import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; +import org.eclipse.microprofile.openapi.annotations.media.Schema; import java.util.List; @@ -51,10 +52,15 @@ public class SimpleReqAffiliation { @AllArgsConstructor @RegisterForReflection public static class AffiliationMember { + @Schema(description = "Nom du membre", example = "Doe") String lname; + @Schema(description = "Prénom du membre", example = "John") String fname; + @Schema(description = "Email du membre", example = "john.doe@test.com") String email; + @Schema(description = "Numéro de licence du membre", example = "12345") int licence; + @Schema(description = "Rôle du membre", example = "MEMBRE") RoleAsso role; } } diff --git a/src/main/java/fr/titionfire/ffsaf/rest/from/AffiliationRequestForm.java b/src/main/java/fr/titionfire/ffsaf/rest/from/AffiliationRequestForm.java index 38086de..985510c 100644 --- a/src/main/java/fr/titionfire/ffsaf/rest/from/AffiliationRequestForm.java +++ b/src/main/java/fr/titionfire/ffsaf/rest/from/AffiliationRequestForm.java @@ -6,63 +6,104 @@ import jakarta.ws.rs.FormParam; import jakarta.ws.rs.core.MediaType; import lombok.Getter; import lombok.ToString; +import org.eclipse.microprofile.openapi.annotations.enums.SchemaType; +import org.eclipse.microprofile.openapi.annotations.media.Schema; import org.jboss.resteasy.reactive.PartType; @Getter @ToString public class AffiliationRequestForm { + @Schema(description = "L'identifiant de l'affiliation. (null si nouvelle demande d'affiliation)") @FormParam("id") private Long id = null; + @Schema(description = "Le nom de l'association.", example = "Association sportive", required = true) @FormParam("name") private String name = null; + + @Schema(description = "Le numéro SIRET de l'association.", example = "12345678901234", required = true) @FormParam("siret") private Long siret = null; + + @Schema(description = "Le numéro RNA de l'association. (peut être null)", example = "W123456789") @FormParam("rna") private String rna = null; + + @Schema(description = "L'adresse de l'association.", example = "1 rue de l'exemple, 75000 Paris", required = true) @FormParam("adresse") private String adresse = null; + + @Schema(description = "La saison de l'affiliation.", example = "2025", required = true) @FormParam("saison") private int saison = -1; + @Schema(description = "Le statut de l'association.", type = SchemaType.ARRAY, implementation = byte.class) @FormParam("status") @PartType(MediaType.APPLICATION_OCTET_STREAM) private byte[] status = new byte[0]; + @Schema(description = "Le logo de l'association.", type = SchemaType.ARRAY, implementation = byte.class) @FormParam("logo") @PartType(MediaType.APPLICATION_OCTET_STREAM) private byte[] logo = new byte[0]; + @Schema(description = "Le nom du premier membre de l'association.", example = "Doe", required = true) @FormParam("m1_nom") private String m1_lname = null; + + @Schema(description = "Le prénom du premier membre de l'association.", example = "John", required = true) @FormParam("m1_prenom") private String m1_fname = null; + + @Schema(description = "L'adresse e-mail du premier membre de l'association.", example = "john.doe@test.com", required = true) @FormParam("m1_mail") private String m1_email = null; + + @Schema(description = "Le numéro de licence du premier membre de l'association. (null si non licencié)", example = "12345") @FormParam("m1_licence") private String m1_lincence = null; + + @Schema(description = "Le rôle du premier membre de l'association. (doit être PRESIDENT)", example = "PRESIDENT", required = true) @FormParam("m1_role") private RoleAsso m1_role = null; + @Schema(description = "Le nom du deuxième membre de l'association.", example = "Xavier", required = true) @FormParam("m2_nom") private String m2_lname = null; + + @Schema(description = "Le prénom du deuxième membre de l'association.", example = "Login", required = true) @FormParam("m2_prenom") private String m2_fname = null; + + @Schema(description = "L'adresse e-mail du deuxième membre de l'association.", example = "xavier.login@test.com", required = true) @FormParam("m2_mail") private String m2_email = null; + + @Schema(description = "Le numéro de licence du deuxième membre de l'association. (null si non licencié)", example = "04242") @FormParam("m2_licence") private String m2_lincence = null; + + @Schema(description = "Le rôle du deuxième membre de l'association.", example = "SECRETAIRE", required = true) @FormParam("m2_role") private RoleAsso m2_role = null; + @Schema(description = "Le nom du troisième membre de l'association.", example = "Doe2", required = true) @FormParam("m3_nom") private String m3_lname = null; + + @Schema(description = "Le prénom du troisième membre de l'association.", example = "John2", required = true) @FormParam("m3_prenom") private String m3_fname = null; + + @Schema(description = "L'adresse e-mail du troisième membre de l'association.", example = "john.doe22@test.com", required = true) @FormParam("m3_mail") private String m3_email = null; + + @Schema(description = "Le numéro de licence du troisième membre de l'association. (null si non licencié)") @FormParam("m3_licence") private String m3_lincence = null; + + @Schema(description = "Le rôle du troisième membre de l'association.", example = "MEMBREBUREAU", required = true) @FormParam("m3_role") private RoleAsso m3_role = null; diff --git a/src/main/java/fr/titionfire/ffsaf/rest/from/AffiliationRequestSaveForm.java b/src/main/java/fr/titionfire/ffsaf/rest/from/AffiliationRequestSaveForm.java index 495b1d9..ac3012b 100644 --- a/src/main/java/fr/titionfire/ffsaf/rest/from/AffiliationRequestSaveForm.java +++ b/src/main/java/fr/titionfire/ffsaf/rest/from/AffiliationRequestSaveForm.java @@ -5,71 +5,126 @@ import jakarta.ws.rs.FormParam; import jakarta.ws.rs.core.MediaType; import lombok.Getter; import lombok.ToString; +import org.eclipse.microprofile.openapi.annotations.media.Schema; import org.jboss.resteasy.reactive.PartType; @Getter @ToString public class AffiliationRequestSaveForm { + @Schema(description = "L'identifiant de l'affiliation.", example = "1", required = true) @FormParam("id") private Long id = null; + + @Schema(description = "Le nom de l'association.", example = "Association sportive", required = true) @FormParam("name") private String name = null; + + @Schema(description = "Le numéro SIRET de l'association.", example = "12345678901234", required = true) @FormParam("siret") private Long siret = null; + + @Schema(description = "Le numéro RNA de l'association. (peut être null)", example = "W123456789") @FormParam("rna") private String rna = null; + + @Schema(description = "L'adresse de l'association.", example = "1 rue de l'exemple, 75000 Paris", required = true) @FormParam("address") private String address = null; + @Schema(description = "Le statut de l'association.") @FormParam("status") @PartType(MediaType.APPLICATION_OCTET_STREAM) private byte[] status = new byte[0]; + + @Schema(description = "Le logo de l'association.") @FormParam("logo") @PartType(MediaType.APPLICATION_OCTET_STREAM) private byte[] logo = new byte[0]; + @Schema(description = "Mode utiliser pour la sauvegarde du membre 1 (0 = licence mode, 2 = nom, prénom)", example = "0", required = true) @FormParam("m1_mode") private Integer m1_mode = null; + + @Schema(description = "Le rôle du premier membre de l'association.", example = "PRÉSIDENT", required = true) @FormParam("m1_role") private RoleAsso m1_role = null; + + @Schema(description = "Le numéro de licence du premier membre de l'association. (null si non licencié)", example = "1234567", required = true) @FormParam("m1_licence") private String m1_lincence = null; + + @Schema(description = "Le nom du premier membre de l'association.", example = "Dupont", required = true) @FormParam("m1_lname") private String m1_lname = null; + + @Schema(description = "Le prénom du premier membre de l'association.", example = "Jean", required = true) @FormParam("m1_fname") private String m1_fname = null; + + @Schema(description = "L'adresse e-mail du premier membre de l'association.", example = "jean.dupont@example.com", required = true) @FormParam("m1_email") private String m1_email = null; + + @Schema(name = "keep_email", + description = "Conserver l'email de la base de donner (1 = conserve, 0 = replacer par 'm1_email')", example = "1", required = true) @FormParam("m1_email_mode") private Integer m1_email_mode = null; + @Schema(description = "Mode utiliser pour la sauvegarde du membre 2 (0 = licence mode, 2 = nom, prénom)", example = "0", required = true) @FormParam("m2_mode") private Integer m2_mode = null; + + @Schema(description = "Le rôle du deuxième membre de l'association.", example = "TRÉSORIER", required = true) @FormParam("m2_role") private RoleAsso m2_role = null; + + @Schema(description = "Le numéro de licence du deuxième membre de l'association. (null si non licencié)", example = "2345678", required = true) @FormParam("m2_licence") private String m2_lincence = null; + + @Schema(description = "Le nom du deuxième membre de l'association.", example = "Durand", required = true) @FormParam("m2_lname") private String m2_lname = null; + + @Schema(description = "Le prénom du deuxième membre de l'association.", example = "Paul", required = true) @FormParam("m2_fname") private String m2_fname = null; + + @Schema(description = "L'adresse e-mail du deuxième membre de l'association.", example = "paul.durand@example.com", required = true) @FormParam("m2_email") private String m2_email = null; + + @Schema(name = "keep_email", + description = "Conserver l'email de la base de donner (1 = conserve, 0 = replacer par 'm2_email')", example = "1", required = true) @FormParam("m2_email_mode") private Integer m2_email_mode = null; + @Schema(description = "Mode utiliser pour la sauvegarde du membre 3 (0 = licence mode, 2 = nom, prénom)", example = "0", required = true) @FormParam("m3_mode") private Integer m3_mode = null; + + @Schema(description = "Le rôle du troisième membre de l'association.", example = "SECRÉTAIRE", required = true) @FormParam("m3_role") private RoleAsso m3_role = null; + + @Schema(description = "Le numéro de licence du troisième membre de l'association. (null si non licencié)", example = "3456789", required = true) @FormParam("m3_licence") private String m3_lincence = null; + + @Schema(description = "Le nom du troisième membre de l'association.", example = "Martin", required = true) @FormParam("m3_lname") private String m3_lname = null; + + @Schema(description = "Le prénom du troisième membre de l'association.", example = "Pierre", required = true) @FormParam("m3_fname") private String m3_fname = null; + + @Schema(description = "L'adresse e-mail du troisième membre de l'association.", example = "pierre.martin@example.com", required = true) @FormParam("m3_email") private String m3_email = null; + + @Schema(name = "keep_email", + description = "Conserver l'email de la base de donner (1 = conserve, 0 = replacer par 'm3_email')", example = "1", required = true) @FormParam("m3_email_mode") private Integer m3_email_mode = null; @@ -84,7 +139,7 @@ public class AffiliationRequestSaveForm { private String email; private Integer email_mode; - public Member(int n){ + public Member(int n) { if (n == 1) { mode = m1_mode; role = m1_role; diff --git a/src/main/java/fr/titionfire/ffsaf/rest/from/ClubMemberForm.java b/src/main/java/fr/titionfire/ffsaf/rest/from/ClubMemberForm.java index ac752d3..d65f4bc 100644 --- a/src/main/java/fr/titionfire/ffsaf/rest/from/ClubMemberForm.java +++ b/src/main/java/fr/titionfire/ffsaf/rest/from/ClubMemberForm.java @@ -6,39 +6,50 @@ import fr.titionfire.ffsaf.utils.RoleAsso; import jakarta.ws.rs.FormParam; import jakarta.ws.rs.core.MediaType; import lombok.Getter; +import org.eclipse.microprofile.openapi.annotations.media.Schema; import org.jboss.resteasy.reactive.PartType; import java.util.Date; @Getter public class ClubMemberForm { + @Schema(description = "L'identifiant du membre.", example = "1234567", required = true) @FormParam("id") private String id = null; + @Schema(description = "Le nom du membre.", example = "Dupont", required = true) @FormParam("lname") private String lname = null; + @Schema(description = "Le prénom du membre.", example = "Jean", required = true) @FormParam("fname") private String fname = null; + @Schema(description = "La catégorie du membre.", example = "SENIOR", required = true) @FormParam("categorie") private Categorie categorie = null; + @Schema(description = "Le genre du membre.", example = "H", required = true) @FormParam("genre") private Genre genre; + @Schema(description = "Le pays du membre.", example = "FR", required = true) @FormParam("country") private String country; + @Schema(description = "La date de naissance du membre.", required = true) @FormParam("birth_date") private Date birth_date; + @Schema(description = "L'adresse e-mail du membre.", example = "jean.dupont@example.com", required = true) @FormParam("email") private String email; + @Schema(description = "Le rôle du membre dans l'association.", example = "MEMBRE", required = true) @FormParam("role") private RoleAsso role; + @Schema(description = "La photo du membre.") @FormParam("photo_data") @PartType(MediaType.APPLICATION_OCTET_STREAM) private byte[] photo_data = new byte[0]; diff --git a/src/main/java/fr/titionfire/ffsaf/rest/from/FullClubForm.java b/src/main/java/fr/titionfire/ffsaf/rest/from/FullClubForm.java index a9b27d0..26f81f1 100644 --- a/src/main/java/fr/titionfire/ffsaf/rest/from/FullClubForm.java +++ b/src/main/java/fr/titionfire/ffsaf/rest/from/FullClubForm.java @@ -4,49 +4,64 @@ import jakarta.ws.rs.FormParam; import jakarta.ws.rs.core.MediaType; import lombok.Getter; import lombok.ToString; +import org.eclipse.microprofile.openapi.annotations.enums.SchemaType; +import org.eclipse.microprofile.openapi.annotations.media.Schema; import org.jboss.resteasy.reactive.PartType; @ToString @Getter public class FullClubForm { @FormParam("id") + @Schema(description = "Identifiant du club", example = "1", required = true) private String id = null; @FormParam("name") + @Schema(description = "Nom du club", example = "Association sportive", required = true) private String name = null; @FormParam("country") + @Schema(description = "Pays du club", example = "FR", required = true) private String country = null; @FormParam("contact") + @Schema(description = "Les contacts du club", example = "{\"SITE\": \"www.test.com\", \"COURRIEL\": \"test@test.com\"}", required = true) private String contact = null; @FormParam("training_location") + @Schema(description = "Liste des lieux d'entraînement", example = "[{\"text\":\"addr 1\",\"lng\":2.24654,\"lat\":52.4868658},{\"text\":\"addr 2\",\"lng\":2.88654,\"lat\":52.7865456}]", required = true) private String training_location = null; @FormParam("training_day_time") + @Schema(description = "Liste des jours et horaires d'entraînement (jours 0-6, 0=>lundi) (temps en minute depuis 00:00, 122=>2h02)", example = "[{\"day\":0,\"time_start\":164,\"time_end\":240},{\"day\":3,\"time_start\":124,\"time_end\":250}]", required = true) private String training_day_time = null; @FormParam("contact_intern") + @Schema(description = "Contact interne du club", example = "john.doe@test.com") private String contact_intern = null; @FormParam("address") + @Schema(description = "Adresse postale du club", example = "1 rue de l'exemple, 75000 Paris", required = true) private String address = null; @FormParam("rna") + @Schema(description = "RNA du club", example = "W123456789") private String rna = null; @FormParam("siret") + @Schema(description = "Numéro SIRET du club", example = "12345678901234", required = true) private String siret = null; @FormParam("international") + @Schema(description = "Club international", example = "false", required = true) private boolean international = false; @FormParam("status") @PartType(MediaType.APPLICATION_OCTET_STREAM) + @Schema(description = "Le statut de l'association.", type = SchemaType.ARRAY, implementation = byte.class) private byte[] status = new byte[0]; @FormParam("logo") @PartType(MediaType.APPLICATION_OCTET_STREAM) + @Schema(description = "Le logo de l'association.", type = SchemaType.ARRAY, implementation = byte.class) private byte[] logo = new byte[0]; }