Laravel や Symfony で手っ取り早く OpenAPI のドキュメントを作成する

第40回関西PHP勉強会 の発表資料です。

Transcript

1. -BSBWFM
   ΍
   4ZNGPOZ
   ͰखͬऔΓૣ͘
   0QFO"1*
   ͷυΩϡϝϯτΛ࡞੒͢Δ ୈճؔ੢1)1ษڧձ
    4"8
2. $(whoami) ࢯ໊
   Ճ౻
   फҰ࿠
   ࡀ
   ϋϯυϧωʔϜ
   4"8
   9
   چ
   5XJUUFS 
   !B[VLJ@FBUFS
   ؔ੢ͷ
   *5
   ΤϯδχΞ
   ίϛϡχςΟͷ೐΍͔͠୲౰
   ࣗশ
   େࡕࡏॅɾѪ஌ग़਎
   ಘҙ෼໺
   8FC
   ΞϓϦέʔγϣϯ։ൃ
   -BSBWFM
   7VF  ྉཧͷՃ೤࣌ؒΛ୹ॖ͢ΔͨΊʹ
   ڧՐͰௐཧͨ͜͠ͱ͕͋Δͷ͸
   ࣗ෼͚ͩͰ͸ͳ͍͸ͣ ࠓ೔ͷ໎ݴ
3. ͋ͳͨͷϓϩδΣΫτͰ
   "1*
   υΩϡϝϯτ͸
   ଘࡏ͍ͯ͠·͔͢ 
4. ͦͷ
   "1*
   υΩϡϝϯτ͸
   ӕΛ͍͍ͭͯͨΓ͠·ͤΜ͔ 
5. "1*
   ࢓༷ॻͱ࣮૷͕ဃ཭͢Δཧ༝ ʮղऍͷ༨஍ͷ͋Δ࢓༷ॻʯ
   ྫ
   ೔෇΍࣌ࠁͷදݱܗ͕ࣜᐆດ
   ෢ా
   ݑଠ࿠
   !,FOUBSPV5BLFEB
   ͞Μ
   ʮ-BSBWFM
   0QFO"1*
   ʹΑΔ
   ਏ͘ͳ͍
   εΩʔϚۦಈ։ൃʯ
   
   
   Q
   ΑΓҾ༻
   ʮ࢓༷ॻͷ৑௕Խʹա͗ͳ͍࣮૷ʯ
   ਓ͕ؒख࡞ۀͰ࣮૷͢Δͱϛε͕ൃੜ͠͏Δ
   ෢ా
   ݑଠ࿠
   !,FOUBSPV5BLFEB
   ͞Μ
   ʮ-BSBWFM
   0QFO"1*
   ʹΑΔ
   ਏ͘ͳ͍
   εΩʔϚۦಈ։ൃʯ
   
   
   QQ
   ΑΓҾ༻ 
6. 0QFO"1*
   ͱ͸ 3&45
   "1*
   ͷ࢓༷ॻΛදݱ͢ΔͨΊͷඪ४Խن֨
   "1*
   ͷΠϯλϑΣʔεΛఆٛ
   ਓ͚ؒͩͰͳ͘ίϯϐϡʔλ΋࢓༷ΛཧղՄೳ
   ᐆດͳදݱΛഉআͯ͠ղऍͷ༨஍Λͳ͘͢
   "1*
   ࢓༷ॻ͸
   :".-
   +40/
   ܗࣜͰදه
   0QFO"1*
   ʹରԠͨ͠πʔϧ͕
   "1*
   ࢓༷Λղऍͯ͠ར༻Մೳ
   ίϯϐϡʔλ͕ղऍͰ͖ΔΑ͏ʹϑΥʔϚοτ͕ఆΊΒΕ͍ͯΔ
   0QFO"1*
   ͸
   "1*
   ࢓༷ॻͷͨΊͷهड़ݴޠ
   ͱ΋ߟ͑ΒΕΔ 
7. 0QFO"1*
   ͷ࢓༷ॻͷྫ
   :".-
   ܗࣜ  openapi: 3.0.0 info: title: Sample description: 'Sample API' version: 1.0.0 paths: '/api/hoge/{id}': get: parameters: - name: id in: path description: 'ID of hoge' required: true schema: type: string responses: 200: description: 'hoge response body' content: application/json: schema: properties: id: type: integer message: type: string type: object
8. 0QFO"1*
   ͕͋Ε͹
   ࢓༷ॻͷ՝୊͸ղফͰ͖Δ͔ 
9. 0QFO"1*
   ୯ମͰ͸࣮૷ͱͷဃ཭໰୊͸ղܾ͠ͳ͍ ࣮૷͕มߋ͞ΕͨΒ
   0QFO"1*
   ͷϑΝΠϧ΋มߋ͕ඞཁ
   υΩϡϝϯτͷมߋ࿙Ε΍ޡͬͨมߋʹΑ࣮ͬͯ૷ͱͷဃ཭͕ੜ͡ΔՄೳੑ͕͋Δ
   ن໛͕େ͖͍
   :".-
   ΍
   +40/
   ͸ਓ͕ؒಡΈॻ͖͢Δʹ͸ਏ͍
   ࢓༷ͷ৑௕ԽͰ͋Δ͜ͱʹมΘΓ͸ͳ͍
   ࣮૷͸
   0QFO"1*
   ͷ಺༰Λॻ͖௚ͨ͠΋ͷʹա͗ͳ͍
   0QFO"1*
   ΛղऍՄೳͳςετπʔϧͰ࢓༷ͱ࣮૷ͷဃ཭ͷݕग़͸Մೳ 
10. ࣮૷͔Β
    0QFO"1*
    υΩϡϝϯτΛੜ੒͢Δ "1*
    ͷ࣮૷͔Β
    0QFO"1*
    υΩϡϝϯτΛࣗಈੜ੒
    ϝϦοτ
    ʮ࢓༷ͱ࣮૷ͱΛҰகͤ͞΍͍͢ʯ
    ෢ా
    ݑଠ࿠
    !,FOUBSPV5BLFEB
    ͞Μ
    ʮ-BSBWFM
    0QFO"1*
    ʹΑΔ
    ਏ͘ͳ͍
    εΩʔϚۦಈ։ൃʯ
    Q
    ΑΓҾ༻
    1)1
    ͷ
    0QFO"1*
    υΩϡϝϯτΛੜ੒͢ΔϥΠϒϥϦ
    4ZNGPOZ
    /FMNJP0QFO"QJ#VOEMF
    -BSBWFM
    -
    4XBHHFS 
11. /FMNJP0QFO"QJ#VOEMF 1)1
    ͷΞτϦϏϡʔτΛར༻ͯ͠هड़
    4ZNGPOZ
    ͷ
    #[Route()]
    ͔Β
    "1*
    ͷ
    63-
    Λදݱ
    #[OpenApi\Attributes\Response()]
    ͰϨεϙϯεͷ৘ใΛදݱ
    4XBHHFS
    6*
    ͷϖʔδΛࣗಈతʹੜ੒
    4XBHHFS
    6*
    ͷϖʔδΛੜ੒͢ΔͨΊͷίϚϯυͷ࣮ߦ͕ෆཁ
    4XBHHFS
    6*
    ͷϖʔδʹΞΫηε͢Δ͚ͩͰྑ͍
    4XBHHFS
    6*
    Λར༻͢ΔͨΊʹ͸ผ్ґଘύοέʔδͷΠϯετʔϧ͕ඞཁ 
12. /FMNJP0QFO"QJ#VOEMF
    ͷΠϯετʔϧͱ࣮૷ྫ  # NelmioOpenApiBundle のインストール composer require nelmio/api-doc-bundle # Swagger UI に必要な依存パッケージのインストール composer require symfony/twig symfony/asset /FMNJP0QFO"QJ#VOEMF
    ͷΠϯετʔϧखॱ use OpenApi\Attributes as OA; class SampleController extends AbstractController { #[Route('/hoge/{id}', methods: ['GET'])] #[OA\Response( response: 200, description: 'Get specified hoge data', content: new OA\JsonContent( ref: new Model(type: Hoge::class), ) )] public function get(int $id): JsonRespnose { // 略 } } ࣮૷ྫ app.swagger_ui: path: /api/doc method: GET defaults: { _controller: nelmio_api_doc.controller.swagger_ui } 4XBHHFS
    6*
    Λ༗ޮԽ͢Δઃఆͷྫ
    config/routes/nelmio_api_doc.yaml
13. /FMNJP0QFO"QJ#VOEMF
    Ͱͷ4XBHHFS
    6*
    ͷදࣔྫ 
14. -
    4XBHHFS 1)1
    ͷΞτϦϏϡʔτΛར༻ͯ͠هड़
    #[OpenApi\Attributes\Get()]
    ΍
    #[OpenApi\Post()]
    ͳͲͰ
    63-
    ΍Ϩεϙϯεͷ
    ৘ใΛදݱ
    4XBHHFS
    6*
    Λར༻͢ΔͨΊʹ௥ՃͷύοέʔδͷΠϯετʔϧ͕ෆཁ
    ެࣜυΩϡϝϯτͷ৘ใ͕΍΍ෆ਌੾
    (JU)VC
    ͷ
    8JLJ
    ͕
    -
    4XBHHFS
    ͷυΩϡϝϯτ
    ࣮૷ྫ͸
    1)1%PD
    ͷΞϊςʔγϣϯͷΈ
    ΑΓৄࡉͳϦϑΝϨϯε͕ඞཁͳ৔߹͸
    4XBHHFS1)1
    ͷυΩϡϝϯτΛࢀর 
15. -
    4XBHHFS
    ͷΠϯετʔϧͱ࣮૷ྫ  # L5 Swagger のインストール composer require darkaonline/l5-swagger -
    4XBHHFS
    ͷΠϯετʔϧखॱ use OpenApi\Attributes as OA; class SampleController extends Controller { #[OA\Get( path: '/api/hoge/{id}', summary: 'Get specified hoge data', responses: [ new OA\Response( response: Response::HTTP_OK, description: 'hoge response body', ), ) )] public function get(int $id): JsonRespnose { // 略 } ࣮૷ྫ # ServiceProvider の登録 php artisan vendor:publish --provider \ "L5Swagger\L5SwaggerServiceProvider" # Swagger UI の 生 成 php artisan l5-swagger:generate -
    4XBHHFS
    ͷઃఆͱυΩϡϝϯτੜ੒
16. -
    4XBHHFS
    Ͱͷ4XBHHFS
    6*
    ͷදࣔྫ 
17. ૯ׅ 0QFO"1*
    ʹ͍ͭͯઆ໌
    ίʔυ͔Β
    0QFO"1*
    υΩϡϝϯτΛࣗಈੜ੒͢Δํ๏Λ঺հ
    4ZNGPOZ
    /FMNJP"QJ%PD#VOEMFS
    -BSBWFM
    -
    4XBHHFS 
18. ͝ਗ਼ௌ͋Γ͕ͱ͏͍͟͝·ͨ͠