---
id: adapter-to-openapi
name: to_openapi projection (6-endpoint gateway doc)
status: completed
depends_on: [gateway-routes]
scope: moderate
risk: low
impact: component
level: implementation
tags: [adapters, phase-3]
---

## Description

Port `adapters/to_openapi.rs` from
`/workspace/@alkdev/alknet/crates/alknet-http/src/adapters/to_openapi.rs`:
generate the OpenAPI doc describing the 6 fixed gateway endpoints
(search/schema/call/batch/subscribe + publish), per-caller surface
discovered via /search (not preloaded), `info.version` semver tracking
the gateway contract (ADR-045; minor = /publish addition), error
schemas projected per ADR-023. Wire `GET /openapi.json` in the server
router. Pub ops excluded from /subscribe's tool description but listed
in /search; /publish documents the NDJSON body per OQ-02's resolution.

## Acceptance Criteria

- [x] Projection ported; 6-endpoint doc with correct versioning
- [x] /openapi.json serves it (integration test)
- [x] Doc validates against openapiv3 parsing
- [x] `cargo test` passes

## References

- docs/architecture/http-adapters.md (§to_openapi)
- docs/architecture/decisions/042-openapi-gateway-pattern.md, 045-to-openapi-gateway-spec-versioning.md, 068-gateway-publish-endpoint.md
- Old source: `/workspace/@alkdev/alknet/crates/alknet-http/src/adapters/to_openapi.rs`

## Notes

> Agent fills during implementation.

## Summary

Ported `src/adapters/to_openapi.rs` (6-endpoint gateway doc) plus the
shared `OpenAPISpec` model it produces:

- `src/adapters/openapi_spec.rs`: OpenAPISpec — from_json / from_yaml /
  from_str (JSON-first per ADR-051, yaml_serde 0.10.x YAML 1.2),
  from_value, $ref resolution (resolve_ref / resolve_refs_recursive,
  pre-staged for the from_openapi port). Shared by from_openapi
  (consume) and to_openapi (produce).
- `src/adapters/to_openapi.rs`: pure projection emitting the fixed
  6-endpoint doc (search/schema/call/batch/subscribe + publish per
  ADR-068). info.version bumped 1.0.0 -> 1.1.0 (ADR-045 minor bump:
  /publish addition). /publish documents the NDJSON body per OQ-02's
  resolution (operation+chunk first line), 400 oneOf covers
  INVALID_INPUT + INVALID_OPERATION_TYPE. Error schemas projected per
  ADR-023 (protocol statuses, HTTP_<status> passthrough, oneOf merge,
  internal-op exclusion).
- `GET /openapi.json` wired into HttpAdapter's router under the
  bearer-auth layer (serves spec.raw as JSON).

21 tests incl. doc-validates-against-openapiv3 + full /openapi.json
serving test over DuplexStream asserting /publish + 1.1.0 + 6 paths.
136 lib tests green.