Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

OpenApi: optional query and header parameters are documented as nullable

Đã đóng
  • Có gì không ổn?
#9,461 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Một pull request liên quan đã được merge.

  • #9464 của @Marve10s — đã đóng, không merge
  • #9786 của @gcanti — đã merge

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
57/100
Loại issue
Lỗi
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
typescript
Lĩnh vực
api

Hướng nghiên cứu

Start in OpenApi.ts at processParameters, the entry point named in the issue, and trace how optional query and header parameter schemas pass through the representation pipeline. Compare those parameter schemas with the body handling described in the issue, then inspect or add focused tests for OpenApi.fromApi query and header output. Done means optional parameters omit JSON null while preserving the documented string forms, with body behavior unchanged.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

What version of Effect is running?

4.0.5. Also seen on 4.0.0. OpenApi.ts on main is the same as in 4.0.5.

What steps can reproduce the bug?

OpenApi.fromApi documents a query parameter declared with Schema.optional as anyOf: [T, null]. A query string has no way to send null, and the server's query decoder doesn't accept one.

import { Schema } from "effect"
import { HttpApi, HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/http-api"

const Query = Schema.Struct({
  limit: Schema.optional(Schema.FiniteFromString),
  cursor: Schema.optional(Schema.NullOr(Schema.String))
})

const Api = HttpApi.make("api").add(
  HttpApiGroup.make("items").add(
    HttpApiEndpoint.get("list", "/items", { query: Query, success: Schema.String })
  )
)

console.log(JSON.stringify(OpenApi.fromApi(Api).paths["/items"].get.parameters, null, 2))

// What the server does with the `null` the document allows
const decodeQuery = Schema.decodeUnknownExit(Schema.toCodecStringTree(Query))
console.log(decodeQuery({ limit: "null" })._tag) // "Failure"
What is the expected behavior?

limit documented as { "type": "string" } with required: false. required: false already says the parameter can be left out, so the undefined that Schema.optional adds has nothing left to describe.

cursor documented with only the string form of its NullOr, anyOf: [{ "type": "string", "enum": ["null"] }, { "type": "string" }], and no JSON null around it.

What do you see instead?
[
  {
    "name": "limit",
    "in": "query",
    "schema": { "anyOf": [{ "type": "string" }, { "type": "null" }] },
    "required": false
  },
  {
    "name": "cursor",
    "in": "query",
    "schema": {
      "anyOf": [
        { "anyOf": [{ "type": "string", "enum": ["null"] }, { "type": "string" }] },
        { "type": "null" }
      ]
    },
    "required": false
  }
]

cursor shows the mismatch most clearly. Its NullOr gets the query codec's representation, the string "null". The undefined from Schema.optional gets the JSON codec's, where Undefined encodes as null. One parameter ends up described by two codecs.

Additional information
  • Headers have the same problem: headers: Schema.Struct({ "x-trace": Schema.optional(Schema.String) }) comes out as anyOf: [{ "type": "string" }, { "type": "null" }].
  • Bodies are fine. A JSON body does decode null to undefined, so T | null is the right description there.
  • Effect's own HttpApiClient is unaffected, since it drops undefined before building the URL. Clients generated from the document are the ones that break. We generate ours with orval, which types limit as string | null and sends ?limit=null when given null. The service then rejects the request, or, for a plain Schema.String, reads "null" as a real value.
  • Switching to Schema.optionalKey fixes the document. It also makes { limit: undefined } fail to encode, so every caller that builds a query from a possibly-undefined value has to leave the key out by hand, which is what Schema.optional exists to avoid.
  • A possible workaround until it's fixed: an OpenApi.Transform that drops the null member from every parameter where required is false.
  • My guess at the cause, from reading the source: processParameters queues parameter schemas as "properties" ops, and those go through the same representation pipeline as bodies, so an optional property's undefined gets the JSON rule.
Ngôn ngữ chính
TypeScript
Star
16.7k
Fork
808
Merge trung bình
11 giờ 24 phút
Pull request đã merge (30 ngày)
848

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của Effect-TS/effect

Tất cả issue của Effect-TS/effect

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.