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

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

Transcript

1. swaggerͰ͔͍͍ͬ͜ APIυΩϡϝϯτΛ࡞Ζ͏ 2016/5/21 PHPΧϯϑΝϨϯε෱Ԭ2016 ߹ಉձࣾdecr / ౉ลҰ޺(@kaz_29)
2. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 WHO!? ߹ಉձࣾ decr ୅දࣾһ ౉ลҰ޺ WebΞϓϦέʔγϣϯͷ։ൃ iOSΞϓϦέʔγϣϯͷ։ൃ Ϋϥ΢υΠϯϑϥͷߏஙɾӡ༻
3. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
4. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 ࢴͷ࿩͸ ͠·ͤΜ
5. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 APIॻ͍ͯ ·͔͢ʁ
6. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 API Documentͷڞ༗ • Excel / Google SpreadSheet • markdownͰॻ͍ͯڞ༗
7. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 ͳ͔ͳ͔ ໘౗
8. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 API Document • API͕ग़དྷ্͕͔ͬͯΒυΩϡϝϯτΛॻ͘ هड़࿙Ε ࢓༷มߋ΁ͷ௥ै • ڞ௨ͷmodelͷࢀর • όʔδϣϯ؅ཧ
9. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 http://swagger.io/
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/
11. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 https://openapis.org/ http://www.publickey1.jp/blog/15/open_api_initiative.html
12. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 swagger tools • Swagger Core • Swagger Codegen • Swagger UI • Swagger Editor
13. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 swagger tools • Swagger Core • Swagger Codegen • Swagger UI • Swagger Editor
14. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 Community-Driven Language Integrations • Clojure • D • Go • Haskell • Java • Javascript • .NET • node.js • perl • php • python • ruby • scala
15. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 PHP Language Integrations • cakephp-swagger • Swagger-PHP • SwaggerAssertions • php-swaggerize-fastroute-library • SwaggerGen • Jane OpenAPI • gossi/swagger
16. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 PHP Language Integrations • cakephp-swagger • Swagger-PHP • SwaggerAssertions • php-swaggerize-fastroute-library • SwaggerGen • Jane OpenAPI • gossi/swagger
17. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 ࣮ࡍͷ ॻ͖ํ
18. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 VTFS
    IBT
    NBOZ
    CPPLNBSLT
19. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 /api/users 6TFS 6TFS #PPLNBSL #PPLNBSL
20. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 <?php /** * @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
21. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 <?php 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ͷఆٛΛॻ͘
22. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 <?php 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ͷఆٛΛॻ͘
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ͷఆٛΛॻ͘
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ͷఆٛΛॻ͘
25. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 /api/users *OEFY6TFS #PPLNBSL 1BHF*OGP
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
27. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 swagger-uiʹ jsonΛಡ·ͤΔ
28. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
29. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
30. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 ࢀর͍ͯ͠ΔϞσϧͷ ৄࡉ΋දࣔ͞ΕΔ
31. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29
32. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 ͜ΜͳຊΛॻ͍͍ͯΔਓͳͷͰ…
33. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 CI/CD PUSH SWAGGER Document΋ࣗಈެ։
34. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 DEMO
35. SwaggerͰ͔͍͍ͬ͜APIυΩϡϝϯτΛ࡞Ζ͏ @kaz_29 fin.