geek time december 2016 : swagger ii

Swagger IIGeek Time – Décembre 2016

MAZIGH Med BelhassenOLBATI Consultant

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


API REST ?

● Representational State Transfer

● Architecture Client-serveur

● Stateless

● Facile à consommer


Statistiques sur les API REST

source : http://www.programmableweb.com/api-research

http://www.programmableweb.com/api-research


Documentation statistiques● Que serait une API s'il était impossible de

comprendre son mode de fonctionnement ?


Documentation statistiques

Documenter son API REST



une API dite RESTFul devrait pouvoir être utilisée sans documentation !

http://www.maxpou.fr/rest-rmm-model



● Créer une documentation.● Suivre un ensemble de spécifications permettant de

décrire et de documenter une API REST.


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)


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/

http://swagger.io/swagger-editor/


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


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>


Swagger 2 / Spring REST API● Configuration

@Configuration@EnableSwagger2public class SwaggerConfig {

@Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.olbati")) .paths(PathSelectors.any()) .build() .apiInfo(apiInfo()); }


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"


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 = "[email protected]"


Swagger 2 / Spring REST API


Thanks!Any questions?

[email protected]

geek time december 2016 : swagger ii

Software