Spring Boot と Swagger #渋谷java

Transcript

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

   View Slide

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

   View Slide

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

   View Slide

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"
   }
   

   View Slide

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

   View Slide

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

   View Slide

7. • 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ͷίϯτϩʔϥʔ
   

   View Slide

8. SpringFoxΛ
   Spring Boot Ͱ࢖͏
   

   View Slide

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

   View Slide

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

    View Slide

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"
    },
    ɾ
    ɾ
    ɾ
    

    View Slide

12. Swagger UI Λ
    Spring Boot Ͱ࢖͏
    

    View Slide

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
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

18. Tips
    

    View Slide

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

    View Slide

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());
    }
    }
    

    View Slide

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

    View Slide

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ͷྫ
    

    View Slide

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

    View Slide

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

    View Slide

25. ͓͠·͍
    

    View Slide