GitbookからOpenApiへのAPIドキュメント移行

Transcript

1. Gitbook͔Β OpenApi΁ͷ APIυΩϡϝϯτҠߦ
2. طଘߏ੒ : Gitbook + Postman • υΩϡϝϯτԽɺϗεςΟϯά • Gitbook • هड़ํ๏: Markdown • APIͷԠ౴֬ೝ • Postman
3. طଘߏ੒ͷྑ͍ͱ͜Ζ • gitbook.com͕ศར • GithubͰ؅ཧͨ͠υΩϡϝϯτΛϗεςΟϯάͯ͘͠ΕΔ • Ӿཡ੍ݶ΋GithubͷϢʔβʔͰ؅ཧ
4. طଘߏ੒ͷਏΈ • ϝϯςίετ͕େ͖͘ଞͷํࣜ΁ͷҠߦ͕ࠔ೉ • Markdown͸APIͷهड़ʹಛԽ͍ͯ͠ͳ͍ • Boilerplate͕ଟ͘ɺهड़ྔ͕ଟ͍ • Өڹൣғ͕࿙Ε͕ͪ • ࣮૷ͱͷဃ཭͕ൃੜ͍ͯ͘͠ • ͍ͭͷؒʹ͔ෛͷҨ࢈ʹ • ࢀরؔ܎͕໌֬ʹͳͬͯͳ͍ͷͰ࣮૷΋ڞ௨Խ͞Ε͍ͯͳ͍ • GitbookͷMarkdownͰ΋ͳ͍ಠࣗͷه๏
5. ৽͍͠ߏ੒ : OpenAPi + ReDoc + Firebase Hosting + Stoplight Studio • υΩϡϝϯτԽɺϗεςΟϯά • OpenApi • هड़ํ๏: yaml • IDEɺAPIͷԠ౴֬ೝ • Stoplight Studio • htmlԽ • ReDoc • ϗεςΟϯά • Firebase Hosting + Firebase functions
6. ৽͍͠ߏ੒ͷྑ͍ͱ͜Ζ • Open Api͸APIυΩϡϝϯτͷهड़ʹಛ͍ͯ͠ΔͨΊগͳ͍هड़Ͱ͢Ή • গͳ͍Boilerplate • Modelͷࢀরؔ܎͕໌֬ʹͳΔ • APIͷ࣮૷΋໌֬ʹͳΓɺޮ཰తͳ։ൃʹͭͳ͕Δ • ෦෼తʹMarkdownʹ΋ରԠ • Gitbookͷࢿ࢈Λྲྀ༻Ͱ͖Δ • ؔ࿈πʔϧ͕๛෋ • কདྷతͳҠߦͷ༰қ͞ • htmlԽ͢ΔReDoc΍ɺίϚϯυϥΠϯπʔϧͳͲ • Stoplight Studio͕ศར • ϫϯιʔεͰςετ͕Մೳ • APIͷϞοΫαʔόʔͱͯ͠΋࢖͑Διʔείʔυੜ੒ • OpenApiͷυΩϡϝϯτ͔Βίʔυੜ੒
7. ৽͍͠ߏ੒ͷਏΈ • ϗεςΟϯάઌ΍ೝূͳͲ༻ҙ͢Δඞཁ͕͋Δ • ͜Εͱ͍͏IDE͕ͳ͍ʁ • Stoplight Studio͸·ͩத్൒୺ • ݕࡧ΍ࢀরؔ܎ͷࢀর͕ऑ͍ • γϣʔτΧοτ͕·ͩগͳ͍
8. Tips : ෳ਺ͷyamlϑΝΠϧΛϚʔδ • yamlϑΝΠϧΛ෼͚ͯ؅ཧ • scheme(Response΍ɺRequestɺModelͳͲ)ͷՄಡੑΛ্͛ΔͨΊ • ࢀরؔ܎Λҡ࣋͢ΔͨΊhtmlԽ͢Δલʹ1ͭͷyamlʹ·ͱΊΔπʔϧ • ίϚϯυϥΠϯͰҰͭͷyamlʹ·ͱΊͯ͘ΕΔ • Openapi-generator • https://github.com/OpenAPITools/openapi-generator • html্Ͱscheme(Response΍ɺRequestɺModelͳͲ)ΛҰཡԽ͢Δπʔϧ • ReDoc͕ҰཡԽͰ͖ΔΑ͏ʹίϚϯυϥΠϯͰ੔ܗ • openapi-redoc-schema-def • https://github.com/dforest/openapi-redoc-schema-def •
9. Tips : html΁ͷม׵ • ReDocΛ࢖ͬͯhtml΁ม׵ • γϯϓϧͳUI • Swagger-uiΑΓ΋ݟ΍͍͢ • Endpoint΍schemeͷҰཡੑ͕ߴ͍ • ࠨϖΠϯͰҰཡΛදࣔͰ͖Δ
10. Tips : ϗεςΟϯά • Firebase HostingΛར༻ • ReDocͰੜ੒ͨ͠htmlΛΞοϓϩʔυ • Firebase functionsͰBasicೝূ
11. Tips : ӡ༻ϑϩʔ 1. ֤୲౰ऀ͕υΩϡϝϯτΛߋ৽ 2. Github্ͰϓϧϦΫϨϏϡʔ 3. ϚʔδޙʹɺGithub ActionsͰFirebase HostingʹࣗಈతʹΞοϓϩʔυ • Commit͞ΕͨhtmlΛFirebase hostingʹΞοϓϩʔυ
12. Tips : ฤूϧʔϧ • มߋΛ͢͢ΊΔ͏ͪʹ่Εͯߦ͖͕ͪ • APIυΩϡϝϯτʹMarkdownͰॻ͍͓ͯ͘
13. ·ͱΊ • ৽͍͠ߏ੒ (OpenAPi + Redoc + Firebase Hosting + Stoplight Studio)ʹஔ͖׵͑ͨ • υΩϡϝϯτ΋ݟ΍͍͢ͷͰྑ͔ͬͨ • ࠓޙɺυΩϡϝϯτʹ߹ΘͤͨAPIͷϦϑΝΫλϦϯά΋͍ͯ͘͠ • υΩϡϝϯτߋ৽࡞ۀ΋ָʹͳΔ͸ͣͳͷͰɺޮՌΛ֬ೝ͍ͯ͘͠ • υΩϡϝϯτ͔ΒͷCodeੜ੒΋ࢼ͍ͯ͘͠