Spring Boot ͱ Swagger 2015/8/1 ୈेೋճ #ौ୩Java bati (twitter: @bati11_)

໨࣍ • Swagger ͱ͸ • SpringFox • JsonSchema • Swagger CodeGen • σϓϩΠϝϯτύΠϓϥΠϯʹ૊ΈࠐΉ

Swagger ͱ͸ • Web API ͷ࢓༷Λ Swagger ͷϧʔϧʹଇͬͨ JSON Ͱهड़ • Swagger JSON ΛऔΓר֤͘छπʔϧ • ྫ͑͹ɺSwagger UI • σϞαΠτ http://petstore.swagger.io/

JSONͰهड़… { "swagger": "2.0", "info": { "description": "Api Documentation", "version": "1.0", "title": "Api Documentation", "termsOfService": "urn:tos", "contact": { "name": "Contact Email" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0" } }, "host": "localhost:5555", "basePath": "/", "tags": [ { "name": "person-resource", "description": "Person Resource" } ], "paths": { "/persons": { "get": { "tags": [ "person-resource" ], "summary": "index", "operationId": "indexUsingGET", "consumes": [ "application/json" ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/Person" }

JSON ΛखͰॻ͘ͷ͸ਏ͍ͷͰ… • Swagger Editor • ϒϥ΢β্Ͱಈ͘πʔϧ • YAMLɺϦΞϧλΠϜϓϨϏϡʔ • SpringFox • Spring MVC ͳΒͪ͜Βͷબ୒ࢶ΋͋Δ

http://springfox.github.io/springfox/

• SpringͷΞϊςʔγϣϯΛݩʹSwagger JSON Λੜ੒Ͱ͖Δ @RestController @RequestMapping(value = "persons", produces = MediaType.APPLICATION_JSON_VALUE) public class PersonResource { @RequestMapping(method = RequestMethod.GET) public List index() { ɾɾɾ } } SpringFox 4QSJOH#PPUͷίϯτϩʔϥʔ

SpringFoxΛ Spring Boot Ͱ࢖͏

spring-swagger2 ΛґଘϥΠϒϥϦʹ௥Ճ repositories { ɾɾɾ jcenter() } dependencies { ɾɾɾ compile ‘io.springfox:springfox-swagger2:2.0.3’ } CVJMEHSBEMF

Configuration ΫϥεΛ༻ҙ @EnableSwagger2 @Configuration public class SwaggerConfiguration { @Bean public Docket customDocket() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage(“sample.web")) .build(); } }

ىಈͯ͠ /v2/api-docs.json ʹΞΫηε͢Δͱ Swagger JSON ΛऔಘͰ͖Δ $ ./gradlew bootRun $ curl http://localhost:8080/v2/api-docs.json { "swagger": "2.0", "info": { "description": "Api Documentation", "version": "1.0", "title": "Api Documentation", "termsOfService": "urn:tos", "contact": { "name": "Contact Email" }, ɾ ɾ ɾ

Swagger UI Λ Spring Boot Ͱ࢖͏

spring-swagger-ui ΛґଘϥΠϒϥϦʹ௥Ճͯ͠ ىಈ͢Δ repositories { ɾɾɾ jcenter() } dependencies { ɾɾɾ compile ‘io.springfox:springfox-swagger2:2.0.3’ compile 'io.springfox:springfox-swagger-ui:2.0.3' } CVJMEHSBEMF

/swagger-ui.html ʹΞΫηε͢Δͱ API υΩϡ ϝϯτ͕ݟΕΔ

SpringFox ͷ ΞϊςʔγϣϯͰ Swagger JSON ͷ ಺༰Λฤू͢Δ

• ϦΫΤετʹؔΘΔΞϊςʔγϣϯ • @Api, @ApiOperation, @ApiParam

• ϨεϙϯεʹؔΘΔΞϊςʔγϣϯ • @ApiModel, @ApiModelProperty

Tips

LocalDateTimeͷϓϩύςΟΛจࣈྻʹ͢Δ @Bean public Docket customDocket() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage(“sample.web")) .build() .directModelSubstitute(LocalDateTime.class, String.class); }

OptionalͷϓϩύςΟΛจࣈྻʹ͢Δ @Bean public Docket customDocket() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage(“sample.web")) .build() .directModelSubstitute(LocalDateTime.class, String.class) .alternateTypeRules(new OptionalTypeRule(typeResolver)); } private static class OptionalTypeRule extends AlternateTypeRule { public OptionalTypeRule(TypeResolver typeResolver) { super(typeResolver.resolve(Optional.class), typeResolver.resolve(Object.class)); } @Override public ResolvedType alternateFor(ResolvedType type) { return appliesTo(type) ? type.getTypeBindings().getTypeParameters().get(0) : type; } @Override public boolean appliesTo(ResolvedType type) { return Optional.class.isAssignableFrom(type.getErasedType()); } }

JSON Schema • Swagger JSONͷdefinitationsϓϩύςΟ͸ JSON SchemaͰ࢖͑Δ • http://spacetelescope.github.io/ understanding-json-schema/structuring.html • ͚ͲɺnullʹରԠͯ͠ͳ͍ • type: [“string”, “null”] ʹ͢Δඞཁ͕͋Δ

ࣗ෼Ͱඞਢ߲໨Ͱͳ͍ϓϩύςΟΛ type: “hoge” ͔Β type: [“hoge”, “null”] ʹ͢Δ def root = new JsonSlurper().parseText(swaggerJson) root.definitions.entrySet().each { def required = it.value.required if (required != null) it.value.properties.each { if (!required.contains(it.key) && !it.value.containsKey('$ref')) { it.value.type = [it.value.type,"null"] } } } } def jsonBuilder = new JsonBuilder() jsonBuilder (root.definitions) definitions = jsonBuilder.toString() (SPPWZͷྫ

Swagger CodeGen • Swagger JSON ͔ΒίʔυΛࣗಈੜ੒Ͱ͖Δ • ΫϥΠΞϯτଆ΋αʔόʔଆ΋ੜ੒Ͱ͖Δ • ΫϥΠΞϯτίʔυΛ࢖༻Ͱ͖Δ͔ݕ౼த

σϓϩΠϝϯτύΠϓϥΠϯʹ ૊ΈࠐΉ Ϗϧυ ΠϯςάϨʔγϣϯ ςετ 4XBHHFS$PEF(FO 4XBHHFS+40/ +40/4DIFNB ΫϥΠΞϯτϥΠϒϥϦ 4XBHHFS6*

͓͠·͍