OpenAPIにも静的解析とフォーマッターを導入して快適にスキーマ定義する

PHPカンファレンス沖縄2024登壇者決定
https://note.com/phpconokinawa/n/n4ba573074845
PHPカンファレンス沖縄2024
https://phpcon.okinawa.jp/

Transcript

1. #phpcon_okinawa PHPカンファレンス沖縄2024 前夜祭 2024/09/27
2. #phpcon_okinawa 自己紹介 • うーたん ◦ X：@uutan1108 • 株式会社ゆめみ ◦ 新卒２年目 ◦ サーバーサイドエンジニア • 趣味 ◦ アニメを観ること 2
3. #phpcon_okinawa PHPカンファレンス沖縄2024 前夜祭 2024/09/27 3
4. #phpcon_okinawa OpenAPIとは 4 4
5. #phpcon_okinawa OpenAPI とは OpenAPI仕様（旧Swagger仕様） は、REST API用のAPI記述フォー マットです。 OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including https://ohmoriyusuke.github.io/openapi-sample/ What Is OpenAPI? https://swagger.io/docs/specification/about/ 5
6. #phpcon_okinawa paths: /pets: get: summary: List all pets description: Retrieves a list of all pets, with pagination options. parameters: - name: limit in: query description: How many items to return at one time (max 100) required: false schema: type: integer maximum: 100 format: int32 responses: "200": description: A paged array of pets headers: x-next: description: A link to the next page of responses schema: type: string content: application/json: schema: $ref: "#/components/schemas/Pets" https://github.com/OHMORIYUSUKE/openapi-sample/blob/main/openapi.yaml#L17-L51 openapi.yaml 6
7. #phpcon_okinawa paths: /pets: get: summary: List all pets description: Retrieves a list of all pets, with pagination options. parameters: - name: limit in: query description: How many items to return at one time (max 100) required: false schema: type: integer maximum: 100 format: int32 responses: "200": description: A paged array of pets headers: x-next: description: A link to the next page of responses schema: type: string content: application/json: schema: $ref: "#/components/schemas/Pets" https://github.com/OHMORIYUSUKE/openapi-sample/blob/main/openapi.yaml#L17-L51 エンドポイント名 クエリパラメータ レスポンス 7
8. #phpcon_okinawa @openapitools/openapi-generator-cliで OpenAPIのファイルから各言語のスキーマの型 を生成できる ロゴ画像：https://openapi-generator.tech/ 8
9. #phpcon_okinawa $ openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o generated/ts 9
10. #phpcon_okinawa /** * Retrieves a list of all pets, with pagination options. * @summary List all pets * @param {number} [limit] How many items to return at one time (max 100) * @param {*} [options] Override http request option. * @throws {RequiredError} */ listPets: async (limit?: number, options: RawAxiosRequestConfig = {}): Promise<RequestArgs> => { const localVarPath = `/pets`; // use dummy base URL string because the URL constructor only accepts absolute URLs. const localVarUrlObj = new URL(localVarPath, DUMMY_BASE_URL); let baseOptions; if (configuration) { baseOptions = configuration.baseOptions; } const localVarRequestOptions = { method: 'GET', ...baseOptions, ...options}; const localVarHeaderParameter = {} as any; const localVarQueryParameter = {} as any; if (limit !== undefined) { localVarQueryParameter['limit'] = limit; } 自動生成された コード generated/ts/api.ts 10
11. #phpcon_okinawa つまり 11 11
12. #phpcon_okinawa OpenAPI(YAML) 12 スキーマを自動生成 各言語のスキーマの型
13. #phpcon_okinawa OpenAPI(YAML) 13 スキーマを自動生成 各言語のスキーマの型
14. #phpcon_okinawa ソースコードと同じように OpenAPIも丁寧に管理する 14
15. #phpcon_okinawa PHPカンファレンス沖縄2024 前夜祭 2024/09/27 15 15
16. #phpcon_okinawa 静的解析 @stoplight/spectral-cli 16
17. #phpcon_okinawa @stoplight/spectral-cli とは - カスタムルールセット: JSON または YAML オブジェク トを lint するためのカスタムルールを作成します。 - すぐに使えるルールセット: OpenAPI v2 & v3および AsyncAPIドキュメントの検証と lint Custom Rulesets: Create custom rules to lint JSON or YAML objects Ready-to-use Rulesets: Validate and lint OpenAPI v2 & v3 and AsyncAPI Documents @stoplight/spectral-cli https://www.npmjs.com/package/@stoplight/spectral-cli 17
18. #phpcon_okinawa 使い方 18
19. #phpcon_okinawa $ npm install --save-dev @stoplight/spectral-cli @stoplight/spectral-cli をインストール 19
20. #phpcon_okinawa $ spectral lint 'openapi.yaml' 静的解析を実行 20
21. #phpcon_okinawa 静的解析を実行後 open-api-sample % npm run lint > open-api-sample@1.0.0 lint > spectral lint 'openapi.yaml' /project/open-api-sample/openapi.yaml 45:23 error invalid-ref '#/components/schemas/Pats' does not exist paths./pets.get.responses[200].content.application/json.schema.$ref 115:10 warning oas3-unused-component Potentially unused component has been detected. components.schemas.Pets ✖ 2 problems (1 error, 1 warning, 0 infos, 0 hints) スペルミス(パスをミス) を指摘 21
22. #phpcon_okinawa カスタムルールも設定できる 22
23. #phpcon_okinawa 23 extends: "spectral:oas" rules: info-contact: off operation-operationId: error path-params-camel-case: description: パラメータ名は camelCase でなければいけません given: $.paths[*][*].parameters[?(@.in != 'header')] severity: error then: field: "name" function: casing functionOptions: type: camel dont-use-nullable: description: nullable を使う代わりにプロパティを required から除いてください given: $..properties[*] then: field: "nullable" function: undefined .spectral.yaml
24. #phpcon_okinawa PHPカンファレンス沖縄2024 前夜祭 2024/09/27 24 24
25. #phpcon_okinawa フォーマッター Prettier 25
26. #phpcon_okinawa prettier とは Prettierとは？ 意見を取り入れたコード整形ツー ル 多くの言語をサポート ほとんどのエディタと統合できる オプションが少ない What is Prettier? An opinionated code formatter Supports many languages Integrates with most editors Has few options » YAML もサポート している Prettier stable https://prettier.io/26
27. #phpcon_okinawa 使い方 27
28. #phpcon_okinawa $ npm install --save-dev --save-exact prettier prettier をインストール 28
29. #phpcon_okinawa $ prettier --check openapi.yaml フォーマッターを実行 29
30. #phpcon_okinawa open-api-sample % npm run check > open-api-sample@1.0.0 check > prettier --check openapi.yaml Checking formatting... openapi.yaml [error] openapi.yaml: SyntaxError: Nested mappings are not allowed in compact mappings (20:16) [error] 18 | /pets: [error] 19 | get: [error] > 20 | summary: List all pets [error] | ^^^^^^^^^^^^^ [error] > 21 | description: Retrieves a list of all pets, with pagination options. [error] | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ [error] > 22 | operationId: listPets [error] | ^ [error] 23 | tags: [error] 24 | - pets [error] 25 | parameters: All matched files use Prettier code style! descriptionのインデント がずれていることを指摘 30
31. #phpcon_okinawa PHPカンファレンス沖縄2024 前夜祭 2024/09/27 31 31
32. #phpcon_okinawa そして、多分、 32 32
33. #phpcon_okinawa OpenAPI(YAML) 33 スキーマを自動生成 各言語のスキーマの型
34. #phpcon_okinawa OpenAPI(YAML) 34 スキーマを自動生成 各言語のスキーマの型
35. #phpcon_okinawa OpenAPIを丁寧に書けば 素敵なスキーマの型になるはず。 35
36. #phpcon_okinawa 最後に 36
37. #phpcon_okinawa 37 10/01 京都 はてなさんオフィス 10/02 東京 ピクシブさんオフィス