Comments (6)
My specific use case is to document an API endpoint which can respond with a fixed set of response tokens, under the same HTTP status code. Overriding the response schema for this endpoint would make explicit in the spec what content should be expected, e.g. using an enum definition.
I agree that sharing a global error model across the API is definitely desirable for consistency. The rationale for this proposal is to give the possibility to step out of the convention for some endpoints when the global model is not sufficient to document them thoroughly.
That said, after thinking a bit more about a possible implementation, I have doubts about whether this feature would play nice with Huma resolvers and ErrorXXXStatus HTTP errors
from huma.
@lsdch I'm not opposed to such a change if it can work. I'm willing to review and merge if you wanted to try it.
@davidolrik for healthz
& readyz
I would recommend just using the underlying router directly. These are usually internal implementation details of the service used by networking & cluster infrastructure like k8s to manage internal resources rather than being exposed publicly for clients to call. An added benefit of doing this is that it won't show up in the API docs which could be confusing to users. Something like (assuming Chi as the router):
type Checks struct {
Live bool `json:"live"`
DB bool `json:"db"`
}
type Ready struct {
Ready bool `json:"ready"`
Version string `json:"version"`
}
router.Get("/readyz", func(w http.ResponseWriter, r *http.Request) {
ready := &Ready{
// TODO: compute ready or not
}
b, err := json.Marshal(ready)
// TODO: handle error
if !ready.Ready {
w.WriteHeader(http.StatusServiceUnavailable)
}
// If WriteHeader is never called it defaults to HTTP 200
w.Write(b)
})
Part of the advantage of Huma is that sometimes it can get out of the way when you don't really need it 😁
from huma.
@davidolrik you can still document it manually by setting api.OpenAPI().Paths["/readyz"].Get...
. If you don't want to manually write a JSON Schema you can also use api.OpenAPI().Components.Schemas.Schema(reflect.TypeOf(MyType{}), true, "hint")
.
Another alternative is to use a Status int
field in your response struct, which will enable you to set 201
vs 200
etc. See https://huma.rocks/features/response-outputs/#status-code. Huma just won't know what values you might set in that field so it potentially requires a little manual documentation.
from huma.
@lsdch you're right I don't think this is easy right now. I'm curious what the use-case is. The idea behind a single error type is that the API is consistent and predictable in how it responds, so changing the response structure of errors for a single operation is kind of counter to that idea.
You could also potentially use a Huma transformer for this (i.e. "if the operation is foo, and the response is an error, then convert it to another type") or just eschew Huma altogether and just use your underlying router directly for this one special operation, potentially manually adding docs via api.OpenAPI().Paths[...]
.
from huma.
I was just looking for something like this for my healthz
endpoints.
My use case is a /readyz
endpoint that returns the status of all dependencies and an overall "are we ready to receive requests" status.
All the load balancer needs is a 200 or a 503, but the body is the same for both cases, like so:
{
"$schema": "https://127.0.0.1:3000/schemas/ReadyzResponseBody.json",
"checks": {
"live": true,
"database": true
},
"ready": true,
"version": "0.42.0-1-deadbeef-devel"
}
from huma.
@danielgtaylor I see your point, but I like to document everything - and I find great value in being able to see which dependency that is currently broken, and often clients do too.
Guess what I really want, is a way to set the http response code for any response.
E.g. a POST
endpoint that returns 201
when creating a resource, and 200
when updating it.
from huma.
Related Issues (20)
- Feature: Accept valueless path/query/header/cookie tags
- Docs UI doesn't handle multiple cookies properly HOT 1
- Allow custom Transform for nested objects HOT 2
- Error thrown when setting cli name HOT 2
- Error return for huma.StreamResponse.Body HOT 1
- Schema(r huma.Registry) *huma.Schema not working on Pointer
- Validation errors localization HOT 2
- Question: Is there a way to add comments to fields? HOT 1
- Version Chi v4 Into Separate Release
- Removing schema reference in response HOT 2
- Multiline doc description for struct fields
- Bug: API doc hidden is not *real* hidden HOT 1
- Allow custom query param types.
- Required query parameter not going through validation when it is omitted HOT 1
- Generating Huma Code from OpenAPI Spec HOT 2
- Generating the openapi.json offline HOT 2
- Defining Servers Causes 404 from OpenAPI Endpoint HOT 1
- Unexported Fields in Schemas are Not Considered for Schema Generation HOT 2
- Any sample code to get http.Request.RemoteAddr in huma.context
- The validation of format:"email" is not perfect. HOT 3
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from huma.