Presentation swagger
-
Upload
francois-robert -
Category
Software
-
view
117 -
download
1
Transcript of Presentation swagger
![Page 1: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/1.jpg)
![Page 2: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/2.jpg)
SWAGGERLe code pour documentation
![Page 3: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/3.jpg)
RESTREpresentational State Transfer
![Page 4: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/4.jpg)
RESTREpresentational State Transfer
• Principe d’architecture • Sans état • Avantages premier
• Respect du standard HTTP (Verbes GET, POST) • Plus simple & moins verbeux que SOAP
![Page 5: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/5.jpg)
Documenter une APINon standard
Non VERSIONNABLE
Non UTILISABLE
![Page 6: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/6.jpg)
SWAGGER
• Description d’une API REST • Grammaire JSON / YAML • Équivalent du WSDL du SOAP • Standard de fait
C’est quoi ?
![Page 7: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/7.jpg)
SWAGGER
• Aucun standard ne s’impose • WADL (Web Application Description Language)
• Soumis au W3C par sun en 2009 mais non standardisé
Alternatives ?
![Page 8: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/8.jpg)
SWAGGERVersion 2.0
• Initié en 2014 • Un seul fichier JSON • Support du markdown
![Page 9: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/9.jpg)
SWAGGER
• jax-rs • Spring • nodeJS • go(lang) • Python • etc…
Intégration
• Swagger codegen • swagger editor • Swagger UI • Génération documents • plugin(s) intelliJ • container UI & editor
Outillage
écosystème
![Page 10: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/10.jpg)
SWAGGERswagger editor
![Page 11: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/11.jpg)
SWAGGERswagger editor
![Page 12: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/12.jpg)
SWAGGERUI
![Page 13: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/13.jpg)
SWAGGERUI
2 types d’intégration
Serveur distinct
Pour • Centralisation • Annuaire Contre • Gestion CORS
Intégration à l’APIPour • Localisation • Facilité Contre • Gestion sécurité
![Page 14: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/14.jpg)
SWAGGERintégration jax-rs et swagger-core
S’appui sur les annotations jax-rs (jsr 311)
Fourni son propre jeu d’annotation pour enrichir la description de l’API
![Page 15: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/15.jpg)
SWAGGER@SwaggerUIConfiguration@ApplicationPath("api") @SwaggerDefinition( info = @Info(title = "swagger-ui-integration demo", version = "1" , description = "Global description for basic application demo") , tags = { @Tag(name = "person", description = "Action on person !!") , @Tag(name = "address", description = "Action on address management") }) public class SimpleApplicationConfiguration extends Application {}
Description initiale de l’API
![Page 16: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/16.jpg)
SWAGGER@SwaggerUIConfiguration@ApplicationPath("api") @SwaggerDefinition( info = @Info(title = "swagger-ui-integration demo", version = "1" , description = "Global description for basic application demo") , tags = { @Tag(name = "person", description = "Action on person !!") , @Tag(name = "address", description = "Action on address management") }) public class SimpleApplicationConfiguration extends Application {}
Description initiale de l’API
@SwaggerDefinition() Définition générale de l’API
@Info() Information de l’API
@Tag() Chapitre fonctionnel de l’API
![Page 17: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/17.jpg)
SWAGGERDescription d’un endpoint global
@Path("person") @Produces({ "application/json", "application/xml"}) @Api(tags = "person") public class PersonEndpoint {
… }
@Api() Description du endpoint
@Tag() Rattachement au chapitre
![Page 18: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/18.jpg)
SWAGGERDescription d’un endpoint GET liste
@GET@Produces({ "application/json", "application/xml"}) @ApiOperation( value = "get list of person" , notes = "if no person already persited, provide a empty list" , response = Person.class , responseContainer = "List") public List<Person> getPersonList() { return personService.getList(null);}
@ApiOpération() Opération lié au endpoint
![Page 19: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/19.jpg)
SWAGGERDescription d’un endpoint GET unitaire
@GET@Path("{personId:[0-9]*}") @Produces({ "application/json", "application/xml"}) @ApiOperation( value = "get person by Id") @ApiResponses({ @ApiResponse(code = 200, message = "success", response = Person.class) , @ApiResponse(code = 404, message = "Person not found", response = String.class) }) public Person getPerson(@PathParam("personId") Integer personId) throws PersonNotExistException { return personService.get(personId);}
@ApiOpération() Opération lié au endpoint
@ApiResponses() Liste des réponses possible
@ApiResponse() Description d’une réponse
![Page 20: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/20.jpg)
SWAGGERDescription d’un endpoint GET unitaire
@GET@Path("{personId:[0-9]*}") @Produces({ "application/json", "application/xml"}) @ApiOperation( value = "get person by Id") @ApiResponses({ @ApiResponse(code = 200, message = "success", response = Person.class) , @ApiResponse(code = 404, message = "Person not found", response = String.class) }) public Person getPerson(@PathParam("personId") Integer personId) throws PersonNotExistException { return personService.get(personId);}
Description du type
![Page 21: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/21.jpg)
SWAGGERDescription d’un endpoint POST
@POST@Consumes("application/x-www-form-urlencoded") @ApiOperation("Create person") public Response createPerson( @FormParam("firstname") String firstName , @FormParam("lastname") String lastName) throws PersonAlreadyPersisted { Person person = personService.persist(new Person(firstName, lastName)); URI personUri = UriBuilder .fromResource(PersonEndpoint.class) .path(String.valueOf(person.getId())) .build(); return Response.created(personUri).build();}
@ApiOpération() Opération lié au endpoint
![Page 22: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/22.jpg)
SWAGGERDescription d’un endpoint POST
@POST@Consumes("application/x-www-form-urlencoded") @ApiOperation("Create person") public Response createPerson( @FormParam("firstname") String firstName , @FormParam("lastname") String lastName) throws PersonAlreadyPersisted { Person person = personService.persist(new Person(firstName, lastName)); URI personUri = UriBuilder .fromResource(PersonEndpoint.class) .path(String.valueOf(person.getId())) .build(); return Response.created(personUri).build();}
Utilisation des annotation jax-rs pour la documentation des paramètres
![Page 23: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/23.jpg)
SWAGGER
Du code !!!!
![Page 24: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/24.jpg)
SWAGGERLes avantages de Swagger UI
Essayer l’API !!
![Page 25: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/25.jpg)
SWAGGERLes avantages de Swagger UI
Parce que la console, y’a que ça de vrai
Pour essayer dans un navigateur ou REST tools
Résultat de la requête
Code HTTP Résultat de la requête
Et les headers !!!!!
![Page 26: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/26.jpg)
SWAGGERswagger-ui-integration
PUB
Intégration sans effort de swagger et swagger-uiUn import maven et une annotation
3 niveaux de configuration• Au niveau projet (annotation) • Au niveau livrable (fichier de configuration ressources) • Au niveau environnement (fichier de configuration local)
@SwaggerUIConfiguration()
![Page 27: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/27.jpg)
SWAGGERswagger-ui-integration
PUB
Intégration sans effort de swagger et swagger-uiUn import maven et une annotation
3 niveaux de configuration• Au niveau projet (annotation) • Au niveau livrable (fichier de configuration ressources) • Au niveau environnement (fichier de configuration local)
@SwaggerUIConfiguration( apiDocPath = "documentation" , apiDocIndex = "rest-index/index.html" , restApplicationPackageAsRoot = false , restApplicationPackage = "org.shipstone.swagger.demo.ws.rs")
JAVA EE 6 LGPL
version 1.0
![Page 28: Presentation swagger](https://reader031.fdocuments.mx/reader031/viewer/2022021921/58e85bc01a28ab78478b66b7/html5/thumbnails/28.jpg)