Spring Boot と Swagger #渋谷java

1. Spring Boot ͱ Swagger 2015/8/1 ୈेೋճ #ौ୩Java bati (twitter: @bati11_)
2. ໨࣍ • Swagger ͱ͸ • SpringFox • JsonSchema • Swagger CodeGen • σϓϩΠϝϯτύΠϓϥΠϯʹ૊ΈࠐΉ
3. Swagger ͱ͸ • Web API ͷ࢓༷Λ Swagger ͷϧʔϧʹଇͬͨ JSON Ͱهड़ • Swagger JSON ΛऔΓר֤͘छπʔϧ • ྫ͑͹ɺSwagger UI • σϞαΠτ http://petstore.swagger.io/
4. 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" }
5. JSON ΛखͰॻ͘ͷ͸ਏ͍ͷͰ… • Swagger Editor • ϒϥ΢β্Ͱಈ͘πʔϧ • YAMLɺϦΞϧλΠϜϓϨϏϡʔ • SpringFox • Spring MVC ͳΒͪ͜Βͷબ୒ࢶ΋͋Δ
6. http://springfox.github.io/springfox/
7. • SpringͷΞϊςʔγϣϯΛݩʹSwagger JSON Λੜ੒Ͱ͖Δ @RestController @RequestMapping(value = "persons", produces = MediaType.APPLICATION_JSON_VALUE) public class PersonResource { @RequestMapping(method = RequestMethod.GET) public List<Person> index() { ɾɾɾ } } SpringFox 4QSJOH
   #PPUͷίϯτϩʔϥʔ
8. SpringFoxΛ Spring Boot Ͱ࢖͏
9. spring-swagger2 ΛґଘϥΠϒϥϦʹ௥Ճ repositories { ɾɾɾ jcenter() } dependencies { ɾɾɾ compile ‘io.springfox:springfox-swagger2:2.0.3’ } CVJMEHSBEMF
10. Configuration ΫϥεΛ༻ҙ @EnableSwagger2 @Configuration public class SwaggerConfiguration { @Bean public Docket customDocket() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage(“sample.web")) .build(); } }
11. ىಈͯ͠ /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" }, ɾ ɾ ɾ
12. Swagger UI Λ Spring Boot Ͱ࢖͏
13. spring-swagger-ui ΛґଘϥΠϒϥϦʹ௥Ճͯ͠ ىಈ͢Δ repositories { ɾɾɾ jcenter() } dependencies { ɾɾɾ compile ‘io.springfox:springfox-swagger2:2.0.3’ compile 'io.springfox:springfox-swagger-ui:2.0.3' } CVJMEHSBEMF
14. /swagger-ui.html ʹΞΫηε͢Δͱ API υΩϡ ϝϯτ͕ݟΕΔ
15. SpringFox ͷ ΞϊςʔγϣϯͰ Swagger JSON ͷ ಺༰Λฤू͢Δ
16. • ϦΫΤετʹؔΘΔΞϊςʔγϣϯ • @Api, @ApiOperation, @ApiParam
17. • ϨεϙϯεʹؔΘΔΞϊςʔγϣϯ • @ApiModel, @ApiModelProperty
18. Tips
19. LocalDateTimeͷϓϩύςΟΛจࣈྻʹ͢Δ @Bean public Docket customDocket() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage(“sample.web")) .build() .directModelSubstitute(LocalDateTime.class, String.class); }
20. 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()); } }
21. JSON Schema • Swagger JSONͷdefinitationsϓϩύςΟ͸ JSON SchemaͰ࢖͑Δ • http://spacetelescope.github.io/ understanding-json-schema/structuring.html • ͚ͲɺnullʹରԠͯ͠ͳ͍ • type: [“string”, “null”] ʹ͢Δඞཁ͕͋Δ
22. ࣗ෼Ͱඞਢ߲໨Ͱͳ͍ϓϩύςΟΛ 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ͷྫ
23. Swagger CodeGen • Swagger JSON ͔ΒίʔυΛࣗಈੜ੒Ͱ͖Δ • ΫϥΠΞϯτଆ΋αʔόʔଆ΋ੜ੒Ͱ͖Δ • ΫϥΠΞϯτίʔυΛ࢖༻Ͱ͖Δ͔ݕ౼த
24. σϓϩΠϝϯτύΠϓϥΠϯʹ ૊ΈࠐΉ Ϗϧυ ΠϯςάϨʔγϣϯ ςετ 4XBHHFS
    $PEF(FO 4XBHHFS
    +40/ +40/
    4DIFNB ΫϥΠΞϯτϥΠϒϥϦ 4XBHHFS
    6*
25. ͓͠·͍