Effect CommunityEC
Effect Community•6mo ago
TBIQ

Issues with Schema Annotations in Swagger Documentation for URL Parameters

I’m working with the @effect/platform Http api builder. I’m defining my groups using the HttpApiGroup and working on annotating my endpoints. A new endpoint I’m introducing has url params, with the following schema 



export const JobListQuery = Schema.Struct({
  // No description appears
  testField0: Schema.NumberFromString,

  // Description: "a string to be decoded into a number"
  testField1: Schema.NumberFromString.pipe(Schema.greaterThanOrEqualTo(1)),

  // No description appears
  testField2: Schema.NumberFromString.annotations({
    description: "Test field 2"
  }),
  // Description: "Test field 3"
  testField3: Schema.String.annotations({
    description: "Test field 3"
  })
})


I’m adding this to my API group as follows 


typescript 

class JobsApiGroup extends HttpApiGroup.make("jobs")
  .add(
    HttpApiEndpoint.get("listJobs", "/jobs")
      .addSuccess(JobListResponse)
      .addError(InvalidJobQuery, InvalidJobQuery.code)
      .setUrlParams(JobListQuery)
  )
{}


I modeled this off of this section of the docs: https://github.com/Effect-TS/effect/tree/main/packages/platform#setting-url-parameters

My issue is that, my annotations are not as I expect them to be 

testField0: No description appears in spec
testField1: Description is "a string to be decoded into a number”. This is a bit weird, as it’s the same as testField0 just piped to another schema which constrains the value, but the description I get is from the internals of NumberFromString

testField2: No description appears in spec
testField3: Works normally 

I’ve included an image of what my swagger docs look like.

Here is a repro in the playground:
https://effect.website/play/#f4d6bb247a54
Screenshot_2025-07-30_at_2.23.17_PM.png
Was this page helpful?