api7 / api7/aisix

docs: add missing integration guides (streaming, tool-calling, anthropic-messages, embeddings, responses, audio, images, rerank, passthrough, errors-and-retries)

Open
#274 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

documentation enhancement priority-normal
Dominant language
Rust
Stars
157
Forks
32
Avg merge
1h 25m
Merged PRs (30d)
145

Description

Background

Follow-up to #246 (closed by #249). The docs rebuild shipped one of the eleven planned integration pages at full quality, plus a baseline errors-and-retries.md:

  • docs/integration/openai-compatible-api.md — full request-flow mermaid + endpoint surface + auth
  • docs/integration/errors-and-retries.md — status-code table, error.type strings verified against ProxyError

The other ten pages exist but are placeholder-tier and need expansion. Per #240's "Remaining Work Breakdown", they are tracked here as separate doc refinements.

Scope

Expand each page to match the depth of openai-compatible-api.md (request shape, response shape, streaming behavior where applicable, provider compatibility, real curl + SDK example, anchor to the corresponding e2e test):

  • docs/integration/streaming.md — SSE event ordering, abort behavior, partial-chunk semantics
  • docs/integration/tool-calling.md — cross-provider tool-use translation; anchor to tests/e2e/src/cases/tools-cross-provider-e2e.test.ts
  • docs/integration/anthropic-messages.md — full /v1/messages reference; OpenAI → Anthropic translation matrix
  • docs/integration/embeddings.md — providers that implement it, dimension handling
  • docs/integration/responses.md — OpenAI Responses API surface; current OpenAI-provider-only constraint
  • docs/integration/audio.md — transcriptions / translations / speech; per-provider compatibility
  • docs/integration/images.md/v1/images/generations; provider compatibility
  • docs/integration/rerank.md — Jina AI rerank surface (per #229)
  • docs/integration/passthrough.md/passthrough/:provider/*rest semantics, auth boundary

Acceptance criteria

For each page:

  • request body shape with every field documented in a table (type / required / description)
  • response body shape with every observable field
  • error envelope behavior for endpoint-specific failure modes
  • at least one runnable curl example + at least one SDK example where the SDK supports the endpoint
  • citation of the e2e test that pins the contract

References

  • Parent rebuild PR: #249
  • Original integration-guides issue: #246

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by comparing the placeholder pages in docs/integration/ with docs/integration/openai-compatible-api.md and review the linked e2e cases, especially tests/e2e/src/cases/tools-cross-provider-e2e.test.ts. Expand the ten listed guides with the specified request, response, error, compatibility, curl, SDK, and e2e-contract details. Done means every acceptance criterion is covered for each page.

Written by the indexing model from the issue text.

Assessment

Domain
api, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.