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

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

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

B51ca7a51ae1fd06bc536fe83e6113e2?s=128

Kaz Watanabe

May 22, 2016
Tweet

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 VTFSIBTNBOZCPPLNBSLT

  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.