AKStream.Next · 文档中心

OpenAPI, Postman, and Client Assets

OpenAPI, Postman, and Client Assets

Contract assets for a formal release belong under Documentation/SKILL/akstream-next-integration/references:

  • openapi.json
  • postman-collection.json
  • postman-environment.json

The bundled integration Skill contains the 1.0.0.169 public contract with 626 public operations covering business and management APIs. Use the matching assets and check the deployment version for fields and permissions. RTC SDK signatures come from the matching delivered types and sources.

flowchart LR
    A[Matching OpenAPI] --> B[Swagger / code generation]
    A --> C[Postman collection]
    A --> D[Field and endpoint indexes]
    B --> E[Automated contract tests]
    C --> E
    D --> E

Using OpenAPI

Fix the input file and AKStream.Next version when generating clients for target languages. For example:

npx @openapitools/openapi-generator-cli generate \
  -i Documentation/SKILL/akstream-next-integration/references/openapi.json \
  -g typescript-fetch \
  -o generated/typescript

After generating the SDK, manual wrapping is still required for asynchronous commands, file streams, Range, SDP, WebSocket, idempotency, and original error messages. Code generators cannot understand business final states.

Using Postman

After importing the Collection and Environment, set the baseUrl and Token only in Postman's secret/current value; do not export or commit actual values.

Tests for each write interface should:

  • Check for 2xx/202 responses;
  • Save the returned resource or command ID;
  • Provide subsequent status queries;
  • Retain the TraceId and original errors;
  • Clean up test resources created during the session.

Files, WebSockets, and SDP should be tested separately; do not force the use of standard JSON requests as substitutes.

Contract Upgrades

Perform a diff check between the old and new OpenAPI versions before upgrading, focusing at least on:

  • Deleted or renamed paths and fields;
  • Newly added required fields;
  • null/empty string semantics;
  • New status enumerations;
  • Permission changes;
  • Content-Type and file behavior;
  • Pagination defaults and limits;
  • Asynchronous returns changing from synchronous results to command/session.

Clients should ignore unknown response fields and retain an "unknown" state, but must not ignore new required inputs or permission requirements.

Swagger Access Boundaries

Online Swagger/Knife4j and OpenAPI JSON require an interactive WebUI session. API Tokens cannot be used to enumerate document entries. CI, SDKs, and unattended tests should use assets saved with the version.

Release Checklist

Generated assets must correspond to the service of the same commit and the same product version. Stop the release if there is a mismatch between the OpenAPI, interface index, model index, and the number of Postman requests; regenerate and audit first.