swaggerでかっこいい APIドキュメントを作ろう

2016/5/21 PHPカンファレンス福岡2016 LT

Transcript

1. swaggerͰ͔͍͍ͬ͜
   APIυΩϡϝϯτΛ࡞Ζ͏
   2016/5/21 PHPΧϯϑΝϨϯε෱Ԭ2016
   ߹ಉձࣾdecr / ౉ลҰ޺(@kaz_29)
   

   View Slide

2. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
   WHO!?
   ߹ಉձࣾ decr ୅දࣾһ
   ౉ลҰ޺
   WebΞϓϦέʔγϣϯͷ։ൃ
   iOSΞϓϦέʔγϣϯͷ։ൃ
   Ϋϥ΢υΠϯϑϥͷߏஙɾӡ༻
   

   View Slide

3. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
   

   View Slide

4. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
   ࢴͷ࿩͸
   ͠·ͤΜ
   

   View Slide

5. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
   APIॻ͍ͯ
   ·͔͢ʁ
   

   View Slide

6. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
   API Documentͷڞ༗
   • Excel / Google SpreadSheet
   • markdownͰॻ͍ͯڞ༗
   

   View Slide

7. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
   ͳ͔ͳ͔
   ໘౗
   

   View Slide

8. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
   API Document
   • API͕ग़དྷ্͕͔ͬͯΒυΩϡϝϯτΛॻ͘
   هड़࿙Ε
   ࢓༷มߋ΁ͷ௥ै
   • ڞ௨ͷmodelͷࢀর
   • όʔδϣϯ؅ཧ
   

   View Slide

9. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
   http://swagger.io/
   

   View Slide

10. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    What is swagger?
    The goal of Swagger™ is to define a standard, language-
    agnostic interface to REST APIs which allows both humans
    and computers to discover and understand the capabilities
    of the service without access to source code,
    documentation, or through network traffic inspection.
    ਓʹ΋ίϯϐϡʔλͷ྆ํʹ༏͘͠ɺݴޠʹґଘ͠ͳ͍
    ඪ४తͳREST APIͷΠϯλʔϑΣʔεΛఆٛ͢Δ͜ͱɻ(໨ඪ)
    http://swagger.io/getting-started/
    

    View Slide

11. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    https://openapis.org/
    http://www.publickey1.jp/blog/15/open_api_initiative.html
    

    View Slide

12. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    swagger tools
    • Swagger Core
    • Swagger Codegen
    • Swagger UI
    • Swagger Editor
    

    View Slide

13. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    swagger tools
    • Swagger Core
    • Swagger Codegen
    • Swagger UI
    • Swagger Editor
    

    View Slide

14. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    Community-Driven
    Language Integrations
    • Clojure
    • D
    • Go
    • Haskell
    • Java
    • Javascript
    • .NET
    • node.js
    • perl
    • php
    • python
    • ruby
    • scala
    

    View Slide

15. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    PHP Language Integrations
    • cakephp-swagger
    • Swagger-PHP
    • SwaggerAssertions
    • php-swaggerize-fastroute-library
    • SwaggerGen
    • Jane OpenAPI
    • gossi/swagger
    

    View Slide

16. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    PHP Language Integrations
    • cakephp-swagger
    • Swagger-PHP
    • SwaggerAssertions
    • php-swaggerize-fastroute-library
    • SwaggerGen
    • Jane OpenAPI
    • gossi/swagger
    

    View Slide

17. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    ࣮ࡍͷ
    ॻ͖ํ
    

    View Slide

18. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    VTFSIBTNBOZCPPLNBSLT
    

    View Slide

19. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    /api/users
    6TFS
    6TFS
    #PPLNBSL
    #PPLNBSL
    

    View Slide

20. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    /**
    * @SWG\Swagger(
    * basePath="/api",
    * host="phpcon.decr.jp",
    * schemes={"http"},
    * produces={"application/json"},
    * consumes={"application/json"},
    * @SWG\Info(
    * version="1.0.0",
    * title="Swaggerαϯϓϧ PHPΧϯϑΝϨϯε෱Ԭ2016 LT൛",
    * description="Swaggerαϯϓϧ PHPΧϯϑΝϨϯε෱Ԭ2016 LT൛
    ",
    * @SWG\Contact(name="kaz@decr.jp"),
    * @SWG\License(name="ϥΠηϯεදه")
    * ),
    * )
    */
    APIͷఆٛΛॻ͘
    app/Model/Entity/User.php
    

    View Slide

21. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    namespace App\Model\Entity;
    use Cake\ORM\Entity;
    /**
    * User Entity.
    *
    *
    @SWG\Definition(
    * definition="
    User",
    * required={
    * "id", "username", "password", "created", "modified"
    * },
    * @SWG\Property(
    * property="id",
    * type="integer",
    * description="user id"
    * ),
    * @SWG\Property(
    * property="email",
    * type="string",
    * description="ϝʔϧΞυϨε",
    * maxLength=255,
    * ),
    …
    ModelͷఆٛΛॻ͘
    

    View Slide

22. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    namespace App\Controller\Api;
    use App\Controller\AppController;
    /**
    * Users Controller
    *
    * @property \App\Model\Table\UsersTable $Users
    */
    class UsersController extends AppController
    {
    …
    /**
    * Index method
    *
    *
    @SWG\Get(
    *
    path="/users",
    * description="ϢʔβҰཡ",
    * produces={"application/json"},
    * @SWG\Parameter(
    * description="ݕࡧจࣈྻ",
    * in="formData",
    * name="q",
    * required=false,
    * type="string"
    * ),
    * @SWG\Response(
    * response=200,
    * description="औಘ੒ޭ",
    APIͷఆٛΛॻ͘
    

    View Slide

23. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    …
    * @SWG\Response(
    * response=200,
    * description="औಘ੒ޭ",
    * @SWG\Schema(
    * @SWG\Property(
    * property="status",
    * type="boolean",
    * description="ॲཧ݁Ռ",
    * ),
    * @SWG\Property(
    * property="data",
    * type="array",
    * @SWG\Items(ref="#/definitions/IndexUser"),
    * description="Ϣʔβ৘ใ",
    * ),
    * @SWG\Property(
    * property="pagination",
    * ref="#/definitions/PageInfo",
    * description="ϖʔδ৘ใ",
    * ),
    * )
    * ),
    * @SWG\Response(
    * response="404",
    * description="Not Found"
    * ),
    * )
    APIͷఆٛΛॻ͘
    

    View Slide

24. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    …
    * @SWG\Definition(
    * definition="IndexUser",
    * allOf={
    * @SWG\Schema(ref="#/definitions/User"),
    * },
    * @SWG\Property(
    * property="bookmarks",
    * description="ϒοΫϚʔΫҰཡ",
    * type="array",
    * @SWG\Items(ref="#/definitions/Bookmark")
    * ),
    * )
    */
    APIͷఆٛΛॻ͘
    

    View Slide

25. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    /api/users
    *OEFY6TFS
    #PPLNBSL
    1BHF*OGP
    

    View Slide

26. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    Swagger-PHPͰॲཧ
    $ ./app/vendor/bin/swagger ./app/src/ ./app/config/ -o ./api-documents/
    Swagger-PHP 2.0.6
    -----------------
    post /bookmarks
    get /users
    post /users
    get /users/{id}
    put /users/{id}
    delete /users/{id}
    post /php/conferences
    -----------------------
    7 operations documented
    -----------------------
    Written to /srv/application/current/api-documents/swagger.json
    

    View Slide

27. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    swagger-uiʹ
    jsonΛಡ·ͤΔ
    

    View Slide

28. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    

    View Slide

29. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    

    View Slide

30. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    ࢀর͍ͯ͠ΔϞσϧͷ
    ৄࡉ΋දࣔ͞ΕΔ
    

    View Slide

31. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    

    View Slide

32. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    ͜ΜͳຊΛॻ͍͍ͯΔਓͳͷͰ…
    

    View Slide

33. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    CI/CD
    PUSH
    SWAGGER
    Document΋ࣗಈެ։
    

    View Slide

34. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    DEMO
    

    View Slide

35. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
    fin.
    

    View Slide