Repository navigation
fix(openapi)!: describe HTTP response contracts independently of schemas - #107
Merged
Merged
Conversation
This was referenced Sep 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
问题与行为变化
原先
Schematic自动得到200 application/json的响应描述:String的媒体类型错误,自定义类型无法同时提供 schema 和自己的 HTTP 契约,错误状态通常只能落到default。现在数据 schema 与 HTTP 响应描述分离,状态码、媒体类型和响应体由Responsible描述。WithStatus<T, STATUS>同时设置真实 HTTP 状态和文档状态,且无需开启 OpenAPI 即可使用。Result<WithStatus<Json<User>, 201>, WithStatus<Json<ApiError>, 409>>可直接表达成功和错误状态。#[api(responses(response(status = 404, body = "ApiError", description = "Not found")), drop_default)]声明显式响应;content_type可自定义,省略 body 表示无响应体。显式条目按状态覆盖推断值,drop_default删除推断的默认条目。声明仅影响文档。Schematic和Responsible。公开response、empty_response、default_response、merge_responses辅助函数,避免手工拼装整棵 OAS 结构。Result<T, E>合并两侧的响应。相同状态的不同媒体类型被保留,同一媒体类型的不同 schema 使用anyOf;schema 引用继续参与统一组件收集与重写。兼容变化与边界
移除
Schematic -> Responsibleblanket impl、ErrorResponsible和Schematic::empty_body。schema-only 自定义响应/错误需实现Responsible或改用Json<T>/WithStatus等明确 HTTP 类型。README 和迁移指南给出新契约、宏语法和迁移方式。运行时才确定的
(StatusCode, T)状态记录为default;原生Response不推断 body schema。固定状态必须在 100..=599;无响应体状态会清空 body 及相关 headers。外层 WithStatus 与 Axum 的状态 tuple 一样会覆盖内层错误状态,建议将它放在 Result 的成功分支。响应合并支持 schema-level refs;不同的 response-level refs 无法直接组成 union,会在组装时明确失败,应使用内联 Response 包含 schema refs。宏声明不得将所有响应删除。
验证
-D warnings、格式检查通过。GitHub CI:11/11 项检查通过(run
34764773671,commitd779dd7)。Closes #76