$30 off During Our Annual Pro Sale. View Details »

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

uutan1108
September 26, 2024

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

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

uutan1108

September 26, 2024
Tweet

More Decks by uutan1108

Other Decks in Programming

Transcript

  1. #phpcon_okinawa 自己紹介 • うーたん ◦ X:@uutan1108 • 株式会社ゆめみ ◦ 新卒2年目

    ◦ サーバーサイドエンジニア • 趣味 ◦ アニメを観ること 2
  2. #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
  3. #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
  4. #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
  5. #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
  6. #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
  7. #phpcon_okinawa 静的解析を実行後 open-api-sample % npm run lint > [email protected] 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
  8. #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
  9. #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
  10. #phpcon_okinawa open-api-sample % npm run check > [email protected] 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