API開発のためのOpenAPI CLIの使用


As promised , の使い方に飛び込みましょうopenapi-cli . 最初のトピックは半非技術的です:API探査.興味があるかもしれません.
  • あなたは技術ライターです
  • あなたはテスターです
  • あなたは、ヘックAPI探査が何であるかを知りません

  • What is API exploration

    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> .



    openapi stats

    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 preview-docs

    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を使用して、より良いアクセシビリティのサポートのために特別にいくつかのプルの要求を行った.
    注意:リファレンスドキュメントを生成するには redoc-cli , でも私はopenapi-cli ワンストップショップとして.違いは、あなたのテーマで静的なHTMLを生成したいときですfrom this issue .

    openapi split

    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
    
    スプリットを使用するもう一つの理由は、単にAPIを探索していないときです.たとえば、あなたが注釈を駆動されたアプローチに駆動されてから切り替えているときsplitはリファクタリングの良い出発点を作成します.

    openapi lint You may want to do linting 評価または好奇心文脈で:
  • 評価
  • このAPIはOpenAPI標準に対して少なくとも有効ですか?
  • 我々は新しいAPIガイドラインを思いついた.我々の既存のAPIは、それに適合しますか?何回か.
  • 好奇心
  • どのように多くのAPIは、このルールに従うのだろうか?それは一般的です、そして、我々は我々のAPIでそれを適用しなければなりませんか?
  • ご覧の通り、最大の利益openapi lint カスタムルールと設定を使用するときに来る.このトピックは、後の記事では、滞在を調整されます.
    OpenAPIベースのAPI探査についてもっと知りたい場合はArnaud Lauret’s series of articles about jq .