Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Spring Boot と Swagger #渋谷java

06bfc3de5c1b439d2081b8a1f196afd7?s=47 bati11
August 01, 2015

Spring Boot と Swagger #渋谷java

06bfc3de5c1b439d2081b8a1f196afd7?s=128

bati11

August 01, 2015
Tweet

Transcript

  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 ΫϥΠΞϯτϥΠϒϥϦ 4XBHHFS6*

  25. ͓͠·͍