API 설계 중에 openapi cli 사용: 첫 번째 섹션

분명히 API 디자인은 OpenAPI 설명 문서를 작성하는 데 그치지 않는다.우선 OpenAPI를 기반으로 해야 합니까?그렇다면 openapi-cli을 사용하면 생활이 더욱 수월해집니다.

예제 API

Let’s imagine you’ve been asked to create an API for Stargate Network
성문 네트워크는 특수 주소를 통해 식별할 수 있는 공간점으로 구성되어 있다.주소(예를 들어 전화번호)로 전화를 걸면 문과 주소 문 사이에 벌레구멍이 생긴다.문은 물리적 대상이기 때문에 폐기되거나 다른 주소로 이동할 수 있다.
우선 리소스:

주소

Id

주소를 액세스할 수 있습니까?우리 전화해도 돼요?

인간이 알고 있는 마지막 위치(일부 주소는 공간의 고정점이 아니다)

다이얼 업 기호
은하계 내외 주소

번 문의 유일한 주소(

번 문에 분배된다면)

이 주소의 사용 가능한 도어

성문

Id

환경: 수면 위, 수중, 수면 위에 있습니까? 아니면 배 안에 있습니까?

상태: 대문이 정상적으로 작동하거나 파괴되거나 매몰되었습니까?

주소 id 다음은 행동이다.특별한 것은 없습니다. 최소한:

모든 주소 나열

주소 정보 얻기

신규 포트 정보 추가

탑승구 정보 얻기

탑승구 정보 업데이트

주의: 모든 API가 OpenAPI를 기반으로 하는 것은 아니라는 것을 잊지 마십시오.만약 내가 진정한 Stargate 시스템을 설계해야 한다면, 나는GraphQL과 같은 조합을 사용하여 찾고, 이벤트 기반 API를 사용하여 다른 모든 조작을 할 것이다. (아마도 AsyncAPI로 설명할 수 있다.)
OpenAPI 설명 문서를 저장할 장소: YAML 기반 다중 파일git repo를 만듭니다.preliminary analysis에 대한 더 많은 정보를 읽을 수 있습니다.
why’s in the Redocly docs . 이 강좌의 모든 단계에서 as Commit <commit_hash>.을 제출하는 링크를 보실 수 있습니다

재구매의 예는 바로 GitHub에 있습니다.

Repository structure We’re gonna use 은 초기 구조를 생성한 다음에 그것을 약간 조정한다.API 구조를 생성할 디렉토리에서 create-openapi-repo을 실행합니다.기억해야 할 점은 이 도구가git 저장소를 초기화하여 제출하려고 시도할 것입니다. npx create-openapi-repo .
Commit e5b40a5
생성된 파일을 살펴보겠습니다.

docs 디렉토리에는 참조 문서가 포함된 HTML 템플릿이 있습니다.현재 사용자 정의 템플릿이 필요하지 않기 때문에 삭제하고 있습니다.

.gitignore은 최종 OpenAPI 설명 문서를 생성하는 데 사용되는 node_modules과 dist 디렉토리를 무시하도록 설정합니다.

.redocly.yaml은 openapi-cli의 구성 파일입니다.docs 디렉터리를 삭제했기 때문에 referenceDocs.htmlTemplate 옵션을 삭제해야 합니다.

업데이트 LICENSE 잊지 마세요.

package.json은 가장 일반적인 조작을 설정했다.

천천히 읽어 README.md.그것은 사용 가능한 조작을 설명하고 예시적인 공헌 지침을 제공했다.실제 프로젝트에서는 모든 안내서를 파일에 넣기를 원하지 않을 수도 있습니다.

과 마지막이지만 가장 중요하지 않은 openapi 목록.이것이 바로 당신의 API 정의가 있는 곳입니다.거의 모든 하위 디렉터리에 README.md이 있습니다. 이 특정 파일을 만드는 이유를 설명하고 다른 대체 방안을 보여 줍니다.복사해서 붙이기 싫으니까 계속 탐색해;)

이제 시간을 되돌리자.성문네트워크 API 계약은 으로 정의했다.구조 건조 유지에 대한 더 많은 정보는 commit c2b8d11과 this을 보십시오.만약 당신이 나에게서 읽기/구경에 흥미가 있다면 클릭하세요!
주: 이런 천박한 디자인에도 이런 정의는 가장 선진적인 것이 아니다.의식적으로 그것의 일부 문제를 첨가하여 예시를 간소화하였으며, 기타 문제는 이후의 문장에서 복원될 것이다.
나는 심지어 얼마나 많은 세부 사항이 소홀히 되었는지 말하는 것도 아니다.

이

Preview

In the package.json file there is already an action for previewing the docs: openapi preview-docs . To execute it, run in the terminal npm run start .

This starts a server with the generated Redoc reference documentation ( ). 그것은 디스크의 변화를 관찰한다.일반적으로 정의를 작성할 때 정의를 실행하고 docs 또는 Stoplight Studio의 UI로 사용합니다.
알 수도 있고 모를 수도 있으며 Redoc의 모양새를 사용자 정의할 수도 있습니다.이는 referenceDocs(Insomnia Designer) 중 .redocly.yaml절을 통해 완성됐다.일부 옵션은 고급 버전에만 적용됩니다.
옵션은 주제에 영향을 주는 옵션(색상, 글꼴)과 특정 기능을 비활성화하거나 활성화하는 옵션으로 나눌 수 있습니다.예를 들어, requiredPropsFirst: true은 다른 속성 앞에 필요한 속성을 표시합니다.
docs
만나요.

c873f15 제출 시

Linting From time to time you should lint with openapi lint ( ). npm run test을 실행하겠습니다.

➜ npm run test

> [email protected] test /home/aviskase/Projects/openapi-cli-examples
> openapi lint

validating /home/aviskase/Projects/openapi-cli-examples/openapi/openapi.yaml...
[1] openapi/openapi.yaml:1:1 at #/

Servers must be present.

 1 | openapi: 3.0.3
 2 | info:
 … | < 30 more lines >
33 | $ref: components/securitySchemes/api_key.yaml
34 |

Error was generated by the no-empty-servers rule.

/home/aviskase/Projects/openapi-cli-examples/openapi/openapi.yaml: validated in 27ms

❌ Validation failed with 1 error.
run with `--generate-ignore-file` to add all problems to ignore file.

아이구!우리가 잘못했어!등등, docs 규칙 불평 우리는 반드시 no-empty-servers을 정의해야 한다.그러나 servers 이기 때문에 우리의 설명 문서는 유효합니다.이 잘못은 어디에서 왔습니까?.redocly.yaml이 생성될 경우 lint 섹션이 포함됩니다.

lint:
  extends:
    - recommended
  rules:
    no-unused-components: warning

no-empty-servers은 확장된 추천 규칙 집합에서 기원한다.너무 엄격하면 minimal으로 바꿀 수 있습니다.더 많은 오류를 얻기 위해 all으로 변경하십시오.
나는 추천한 규칙을 보류하고 필요하지 않은 규칙을 명확하게 사용하지 않는 것을 좋아한다.OpenAPI specification doesn’t state this as a required field no-empty-servers: off 섹션 Per docs에 rules을 설치해야 합니다.또는 심각도를 warning으로 변경할 수 있습니다.
추가 내장 규칙 commit ee2e3ff에 대한 자세한 내용을 볼 수 있습니다.다음 글에서 사용자 정의 규칙을 추가하는 방법을 보여 드리겠습니다.

파일에서

Bundling Most of the tools require single-file OpenAPI doc. That’s where bundling comes in. The package.json is preconfigured with the script to run openapi bundle -o dist which will save a generated file to the dist directory. Usually it’s enough, but in some cases you may want to run with --derefenreced flag to produce a file with internally inlined definitions ( ).

➜ npm run build

> [email protected] build /home/aviskase/Projects/openapi-cli-examples
> openapi bundle -o dist

bundling /home/aviskase/Projects/openapi-cli-examples/openapi/openapi.yaml...
📦 Created a bundle for /home/aviskase/Projects/openapi-cli-examples/openapi/openapi.yaml at dist.yaml 28ms.

방금 무슨 일이 있었어요?우리가 얻은 것은 ./dist/<filename>.yaml이 아니라 ./dist.yaml이다.왜?
이것은 버그나 특성의 일종이다.만약 당신이 docs을 선택한다면, 이것은 예상한 행동처럼 보이지만, 여전히 사람을 곤혹스럽게 한다.간단히 말해, API 정의가 하나만 있으면 -o에 파일 경로가 필요한 것 같습니다.API 정의가 여러 개인 경우(자세한 내용은 다음 두 번째 섹션에 설명됨) 이 옵션은 디렉토리를 가리킬 수 있습니다.
우리의 예시에서 우리는 API 정의를 가지고 있기 때문에 복원하려면 스크립트를 -o dist/openapi 또는 -o dist/openapi.yaml으로 변경해야 한다.기본적으로 --ext이 yaml과 같으면 이 두 가지 방법의 효과는 같다.JSON 형식의 파일을 생성하려면 -o dist/openapi --ext json 또는 -o dist/openapi.json을 사용하십시오.이 두 가지 형식이 필요하면 명령을 각각 실행해야 합니다. check the code을 참고하십시오.

a4e1e23을 제출할 때

Generating reference doc One of the features that 하지만 내가 필요로 하는 모든 시간은 정적 Redoc html 파일을 생성하는 것이다.네, 더 좋은 해결 방안과 절차에 투자하고 싶을 때, 비교적 작은 규모에서, 개발진이 아닌 사람이 최신이나 원형 API를 보고 싶을 때 간단한 HTML 파일을 보내는 것은 가능합니다.
우선 openapi-cli을 통해 redoc-cli을 설치해야 합니다.그런 다음 npm i redoc-cli에 새 스크립트를 추가하여 package.json 디렉토리에 HTML 파일을 생성합니다.

"docs": "redoc-cli bundle dist/openapi.yaml -o dist/redoc.html"

dist을 실행하고 생성된 파일을 열면 모든 사용자 정의 옵션이 사라진 것을 알 수 있습니다.보십시오. npm run docs은 redoc-cli 프로필을 지원하지 않습니다.이 문제를 해결하려면 .redocly.yaml doesn’t have을 추가하십시오. prepareOptions.js에서 referenceDocs을 읽고 .redocly.yaml에 저장합니다. 그런 다음 준비 스크립트를 실행하려면 .redoc.json 스크립트를 수정하고 docs을 사용하십시오.

"docs": "node plugins/prepareOptions.js && redoc-cli bundle dist/openapi.yaml -o dist/redoc.html --options .redoc.json"

.redoc.json 만나요.

ad6dacc를 제출할 때

IMHO

Personally, I prefer different names for scripts:

• preview instead of start
• lint instead of test
• bundle instead of build
• build for npm run lint && npm run bundle && npm run docs

Then, all I do is jump between npm run preview and npm run build .

See .
오늘은 여기까지.at commit 51c078e에서는 각 저장소에 대한 여러 정의를 관리하는 방법을 보여 드리겠습니다.