Présentation de Swagger II Par Mohamed Belhassen MAZIGH, consultant OLBATI Au Geek Time de Décembre 2016

1. Swagger II
Geek Time – Décembre 2016
MAZIGH Med Belhassen
OLBATI Consultant

2. OLBATI - Geek Time - Décembre 2016 2
Plan
● Rappel sur l'architecture Rest
● Statistiques sur les API REST
● Documentation statistiques
● OpenAPI
● Swagger tools
● Swagger 2 avec Spring REST API
● Démonstration

3. OLBATI - Geek Time - Décembre 2016 3
API REST ?
● Representational State Transfer
● Architecture Client-serveur
● Stateless
● Facile à consommer

4. OLBATI - Geek Time - Décembre 2016 4
Statistiques sur les API REST
source : http://www.programmableweb.com/api-research

5. OLBATI - Geek Time - Décembre 2016 5
Documentation statistiques
● Que serait une API s'il était impossible de
comprendre son mode de fonctionnement ?

6. OLBATI - Geek Time - Décembre 2016 6
Documentation statistiques
Documenter son API REST

7. OLBATI - Geek Time - Décembre 2016 7
Documentation statistiques
une API dite RESTFul devrait pouvoir être utilisée
sans documentation !

8. OLBATI - Geek Time - Décembre 2016 8
Documentation statistiques
● Créer une documentation.
● Suivre un ensemble de spécifications permettant de
décrire et de documenter une API REST.

9. OLBATI - Geek Time - Décembre 2016 9
OpenAPI
● OpenAPI, anciennement connu sous le nom de Swagger
RESTful API, désigne un ensemble de spécifications
permettant de décrire et de documenter une API REST.
● Implémenter ces spécifications permet entre autres :
○ D'obtenir une documentation (Swagger UI)
○ Générer des clients permettant d'interagir avec notre
API (Swagger Codegen)

10. OLBATI - Geek Time - Décembre 2016 10
Swagger Tools
● Le résultat final est un fichier, il peut être rédigé aussi bien en JSON qu'en
YAML.
● Swagger editor:
source : http://swagger.io/swagger-editor/

11. OLBATI - Geek Time - Décembre 2016 11
Swagger Tools
● Swagger UI : Swagger UI is a dependency-free collection
of HTML, Javascript, and CSS assets that dynamically
generate beautiful documentation from a
Swagger-compliant API.
● Swagger codegen : swagger-codegen contains a
template-driven engine to generate documentation, API
clients and server stubs in different languages by parsing
your OpenAPI / Swagger definition

12. OLBATI - Geek Time - Décembre 2016 12
Swagger 2 / Spring REST API
● springfox
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>

13. OLBATI - Geek Time - Décembre 2016 13
Swagger 2 / Spring REST API
● Configuration
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.olbati"))
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}

14. OLBATI - Geek Time - Décembre 2016 14
Swagger 2 / Spring REST API
● API
○ @ApiOperation
■ value = ""
■ nickname = ""
■ notes = ""
■ response = MyClass.class
■ responseContainer = "exp : List"
○ @ApiResponses
■ value = {un ou plusieurs ApiResponse}
○ @ApiResponse
■ code = 200 / 401
■ message = "Success" / "Unauthorized"
■ response = Myclass.class
■ responseContainer = "List"

15. OLBATI - Geek Time - Décembre 2016 15
Swagger 2 / Spring REST API
○ @ApiImplicitParams({un ou plusieurs ApiImplicitParam})
○ @ApiImplicitParam
■ name = "name"
■ value = "User's name"
■ required = false
■ dataType = "string",
■ paramType = "query"
■ defaultValue = "Belhassen"
○ @ApiParam : c’est comme ApiImplicitParam mais
appliquer aux arguments de services.
○ @ApiModel : appliquer sur les Model.
○ @ApiModelProperty
■ position = 1
■ name = "address"
■ required = true
■ value = "The email address of recipient"
■ example = "test00@yopmail.com"

16. OLBATI - Geek Time - Décembre 2016 16
Swagger 2 / Spring REST API

17. OLBATI - Geek Time - Décembre 2016 17
Thanks!
Any questions?
mohamed-belhassen.mazigh@olbati.com