Spectral로 경로가 소문자인지 확인하는 방법

이 게시물에서는 Spectral을 사용하여 OpenAPI 경로의 키에 소문자 영숫자 문자만 사용되는지 확인하는 방법을 보여줍니다.

스펙트럼이란 무엇입니까?

Spectral은 규칙 기반 JSON/YAML 린터입니다. 모든 JSON/YAML을 확인할 수 있지만 특히 OpenAPI용으로 잘 설계되었습니다.

문제

여러 단어가 포함된 경로를 나타내기 위해 camelCase, kebab-case 및 밑줄과 같은 여러 가지 형식 선택이 있습니다.

GET /pullRequests/{id}
GET /pull-requests/{id}
GET /pull_requests/{id}
GET /pullrequests/{id}

팀과 협업할 때 API 디자인 규칙에 따라 어떤 형식을 선택해야 하는지 정의해야 합니다.

그러나 사람들은 종종 실수를 합니다. 그들은 관습을 모르거나 주의 깊게 읽지 못할 수도 있습니다.

솔루션: Spectral로 경로 규칙 확인

이 문제를 해결하려면 Spectral로 확인을 자동화하는 것이 효과적입니다.

경로가 모두 소문자 영숫자인지 확인하는 Spectral 규칙은 다음과 같습니다. 이것을 .spectral.yml에 작성하십시오.

extends: spectral:oas
rules:
  path-keys-lower-case-alphanumeric:
    message: "Path must be lower case. Only lower case alphanumeric characters are allowed."
    given: "$.paths"
    then:
      field: "@key"
      function: pattern
      functionOptions:
        match: "^(?:\\{[^}]+\\}|[/a-z\\d])*$" # https://regex101.com/r/eHmZ29/1

이 규칙을 추가하면 경로에 대문자나 하이픈이 포함된 경우 Spectral이 경고합니다.

$ npx spectral lint openapi-spec.yaml
/path/to/my/openapi-spec.yaml
 17:15  warning  path-keys-lower-case-alphanumeric  Path must be lower case. Only lower case alphanumeric characters are allowed.  paths./pullRequests
 27:23  warning  path-keys-lower-case-alphanumeric  Path must be lower case. Only lower case alphanumeric characters are allowed.  paths./pull-requests

✖ 2 problems (0 errors, 2 warnings, 0 infos, 0 hints)

규칙 세부정보

위에서 소개한 규칙은 Spectral 코어 기능pattern을 사용합니다. 이 함수는 주어진 필드가 정규식과 일치하는지 확인합니다.
^(?:\{[^}]+\}|[/a-z\d])*$는 경로에 소문자 영숫자만 포함되어 있는지 확인하는 정규식입니다. 이 식은 다음 문자열과 일치합니다.

/
/foo
/123
/foobar
/foo123
/{foo}
/{fooBar}
/{foo_bar}
/{foo-bar}
/users
/users/{userId}
/users/{user-id}
/users/{userid}
/users/{user_id}

반면에 다음 문자열은 금지됩니다.

/Foo
/fooBar
/foo-bar
/foo_bar
/temas/{teamId}/MEMBERS/{userId}