API 탐색에 openapi-cli 사용

As promised , openapi-cli 의 사용법에 대해 알아보겠습니다. 첫 번째 주제는 세미 비기술: API 탐색입니다. 다음과 같은 경우 관심을 가질 수 있습니다.
  • 당신은 기술 작가입니다
  • 당신은 테스터입니다
  • 도대체 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.

    Or perhaps you have special needs. Lorna Jane Mitchell in her presentation on Delightful SDKs 그녀는 공식 문서에 액세스할 수 없기 때문에 종종 자신의 로컬 참조 문서를 생성한다고 언급합니다. AFAIK, 그녀는 Redoc을 사용하고 특히 더 나은 접근성 지원을 위해 몇 가지 pull 요청을 했습니다.



    참고: 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 평가 또는 호기심 맥락에서:
  • 평가:
  • 이 오래된 API는 최소한 OpenAPI 표준에 따라 유효합니까? 아니면 완전히 쓰레기입니까?
  • 새로운 API 가이드라인을 마련했습니다. 기존 API가 이를 준수합니까? 얼마나 많은 사람들이 그렇지 않습니까?

  • 호기심:
  • 이 규칙을 따르는 API가 얼마나 많은지 궁금합니다. 일반적이며 API에 적용해야 합니까?


  • 보시다시피 openapi lint의 가장 큰 이점은 사용자 지정 규칙 및 구성을 사용할 때 제공됩니다. 이 주제는 이후 기사에서 다룰 예정이니 계속 지켜봐 주시기 바랍니다.


    OpenAPI 기반 API 탐색에 대해 더 자세히 읽고 싶다면 Arnaud Lauret’s series of articles about jq 을 추천합니다.

    좋은 웹페이지 즐겨찾기