API 탐색에 openapi-cli 사용
openapi-cli
의 사용법에 대해 알아보겠습니다. 첫 번째 주제는 세미 비기술: API 탐색입니다. 다음과 같은 경우 관심을 가질 수 있습니다.API 탐색이란
I use this term akin to exploratory testing. You can search for works of Cem Kaner, James Bach, Michael Bolton, Elisabeth Hendrickson, James Whittaker, but beware, that’s a nice little serpentarium of a field.
In the simplest words, it is a process of learning something about API I don’t know or have a limited information about. That’s it. The main contexts for this activity are:
- Necessity. I want to use some API.
- Curiosity. Just looking at how other APIs are done.
- Assessment. I need to check APIs for certain characteristics.
There are many ways to perform exploration, countless tools and sources to use. In this article I’ll be looking only at OpenAPI description documents, because that’s where openapi-cli
comes handy.
Note: When exploring unknown APIs, I run a globally installed package: npm i -g @redocly/openapi-cli
. Then it is accessible in the terminal as openapi <args>
.
오픈 API 통계
Gathers some basic statistics for an OpenAPI description document. Can be in “stylish” format (as in the example below) or in JSON.
➜ openapi stats http://localhost:8888/api/v1/swagger.json
Document: http://localhost:8888/api/v1/swagger.json stats:
🚗 References: 12
📦 External Documents: 0
📈 Schemas: 12
👉 Parameters: 9
🔗 Links: 0
➡️ Path Items: 4
👷 Operations: 7
🔖 Tags: 1
Nothing useful for me at the moment. The only use case that comes to mind is when you have a bunch of documents for an assessment and you’re not sure where to start. Then, you can check stats for each doc and proceed with the smallest one.
openapi 미리보기 문서
This command is the primary reason I have openapi-cli
installed as a global package: I use it all the time. The command accepts path or link to the existing OpenAPI description document and starts a local HTTP server with the generated Redoc reference doc.
➜ openapi preview-docs http://localhost/api/v1/swagger.json
Using Redoc community edition.
Login with openapi-cli login or use an enterprise license key to preview with the premium docs.
🔎 Preview server running at http://127.0.0.1:8080
👀 Watching http://localhost/api/v1/swagger.json and all related resources for changes
Bundling...
Created a bundle for http://localhost/api/v1/swagger.json successfully
Why you’d want that?
First, sometimes there is just an OpenAPI description document and nothing else. No documentation whatsoever. Rare, but I do stumble upon this with internal APIs.
The second reason is when there are some reference docs, but they don’t fit you.
For example, it’s a SwaggerUI, and you don’t like it, or the description doc has advanced features like oneOf
or discriminator
. In such case, SwaggerUI cannot generate fancy form-based presentation, so you have to read bare model definitions.
참고:
redoc-cli
을 사용하여 참조 문서를 생성할 수 있지만 저는 openapi-cli
를 원스톱 상점으로 사용하는 것을 선호합니다. 차이점은 테마로 정적 HTML을 생성하려는 경우입니다. 지금은 작은 해킹from this issue을 사용해야 합니다.오픈 API 분할
Reading a big OpenAPI description doc is cumbersome. Especially when you need to jump back and forth between references.
Split for the rescue! It’s an opposite of the bundling operation 참조를 여러 파일로 분리합니다. 하지만 조금 더 똑똑합니다. 예를 들어 경로를 별도의 파일로 분할합니다.경고! 이 명령은 OpenAPI 2를 지원하지 않습니다.
설명 문서를
out
디렉토리openapi split --outDir out openapi.json
로 분할해 보겠습니다. 다음은 샘플 결과입니다.~/out
➜ tree
.
├── components
│ ├── parameters
│ │ ├── pageNumber.yaml
│ │ ├── pageSize.yaml
│ │ └── resourceId.yaml
│ ├── requestBodies
│ │ ├── User.yaml
│ ├── responses
│ │ ├── Error.yaml
│ │ ├── Forbidden.yaml
│ │ ├── Ok.yaml
│ │ └── Unauthorized.yaml
│ └── schemas
│ ├── Id.yaml
│ ├── ResourceId.yaml
│ ├── UserCollection.yaml
│ └── User.yaml
├── openapi.yaml
└── paths
├── users@{id}.yaml
└── users.yaml
split을 사용하는 또 다른 이유는 API를 탐색하는 것이 아니라 작업할 계획일 때입니다. 예를 들어 주석 기반 방식에서 수작업 방식으로 전환할 때 split은 리팩토링을 위한 좋은 출발점을 만듭니다.
오픈 API 린트
You may want to do linting 평가 또는 호기심 맥락에서:보시다시피
openapi lint
의 가장 큰 이점은 사용자 지정 규칙 및 구성을 사용할 때 제공됩니다. 이 주제는 이후 기사에서 다룰 예정이니 계속 지켜봐 주시기 바랍니다.OpenAPI 기반 API 탐색에 대해 더 자세히 읽고 싶다면 Arnaud Lauret’s series of articles about
jq
을 추천합니다.
Reference
이 문제에 관하여(API 탐색에 openapi-cli 사용), 우리는 이곳에서 더 많은 자료를 발견하고 링크를 클릭하여 보았다 https://dev.to/aviskase/using-openapi-cli-for-api-exploration-414d텍스트를 자유롭게 공유하거나 복사할 수 있습니다.하지만 이 문서의 URL은 참조 URL로 남겨 두십시오.
우수한 개발자 콘텐츠 발견에 전념 (Collection and Share based on the CC Protocol.)