Skip to content

Commit

Permalink
docs: README updates & RFC 9457 errors
Browse files Browse the repository at this point in the history
  • Loading branch information
danielgtaylor committed Feb 15, 2024
1 parent 0e5a8bb commit bc86e7e
Show file tree
Hide file tree
Showing 4 changed files with 24 additions and 8 deletions.
20 changes: 18 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
A modern, simple, fast & flexible micro framework for building HTTP REST/RPC APIs in Go backed by OpenAPI 3 and JSON Schema. Pronounced IPA: [/'hjuːmɑ/](https://en.wiktionary.org/wiki/Wiktionary:International_Phonetic_Alphabet). The goals of this project are to provide:

- Incremental adoption for teams with existing services
- Bring your own router, middleware, and logging/metrics
- Bring your own router (including Go 1.22+), middleware, and logging/metrics
- Extensible OpenAPI & JSON Schema layer to document existing routes
- A modern REST or HTTP RPC API backend framework for Go developers
- Described by [OpenAPI 3.1](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md) & [JSON Schema](https://json-schema.org/)
Expand All @@ -27,7 +27,7 @@ Features include:
- Request body
- Responses (including errors)
- Response headers
- JSON Errors using [RFC7807](https://tools.ietf.org/html/rfc7807) and `application/problem+json` by default (but can be changed)
- JSON Errors using [RFC9457](https://datatracker.ietf.org/doc/html/rfc9457) and `application/problem+json` by default (but can be changed)
- Per-operation request size limits with sane defaults
- [Content negotiation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation) between server and client
- Support for JSON ([RFC 8259](https://tools.ietf.org/html/rfc8259)) and CBOR ([RFC 7049](https://tools.ietf.org/html/rfc7049)) content types via the `Accept` header with the default config.
Expand All @@ -53,6 +53,14 @@ Features include:

This project was inspired by [FastAPI](https://fastapi.tiangolo.com/). Logo & branding designed by Kari Taylor.

> This is by far my favorite web framework for Go. It is inspired by FastAPI, which is also amazing, and conforms to many RFCs for common web things ... I really like the feature set, the fact that it [can use] Chi, and the fact that it is still somehow relatively simple to use. I've tried other frameworks and they do not spark joy for me. - [Jeb_Jenky](https://www.reddit.com/r/golang/comments/zhitcg/comment/izmg6vk/?utm_source=reddit&utm_medium=web2x&context=3)
> After working with #Golang for over a year, I stumbled upon Huma, the #FastAPI-inspired web framework. It’s the Christmas miracle I’ve been hoping for! This framework has everything! - [Hana Mohan](https://twitter.com/unamashana/status/1733088066053583197)
> I love Huma. Thank you, sincerely, for this awesome package. I’ve been using it for some time now and it’s been great! - [plscott](https://www.reddit.com/r/golang/comments/1aoshey/comment/kq6hcpd/?utm_source=reddit&utm_medium=web2x&context=3)
> Thank you Daniel for Huma. Superbly useful project and saves us a lot of time and hassle thanks to the OpenAPI gen — similar to FastAPI in Python. - [WolvesOfAllStreets](https://www.reddit.com/r/golang/comments/1aqj99d/comment/kqfqcml/?utm_source=reddit&utm_medium=web2x&context=3)
# Install

Install via `go get`. Note that Go 1.20 or newer is required.
Expand Down Expand Up @@ -146,3 +154,11 @@ Even though the example is tiny you can also see some generated documentation at
See the [https://huma.rocks/](https://huma.rocks/) website for full documentation in a presentation that's easier to navigate and search then this README. You can find the source for the site in the `docs` directory of this repo.

Official Go package documentation can always be found at https://pkg.go.dev/github.com/danielgtaylor/huma/v2.

# Articles & Mentions

- [APIs in Go with Huma 2.0](https://dgt.hashnode.dev/apis-in-go-with-huma-20)
- [Reducing Go Dependencies: A case study of dependency reduction in Huma](https://dgt.hashnode.dev/reducing-go-dependencies)
- [Golang News & Libs & Jobs shared on Twitter/X](https://twitter.com/golangch/status/1752175499701264532)
- Featured in [Go Weekly #495](https://golangweekly.com/issues/495)
- [Bump.sh Deploying Docs from Huma](https://docs.bump.sh/guides/bump-sh-tutorials/huma/)
2 changes: 1 addition & 1 deletion docs/docs/features/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Features include:
- Request body
- Responses (including errors)
- Response headers
- JSON Errors using [RFC7807](https://tools.ietf.org/html/rfc7807) and `application/problem+json` by default (but can be changed)
- JSON Errors using [RFC9457](https://tools.ietf.org/html/rfc9457) and `application/problem+json` by default (but can be changed)
- Per-operation request size limits with sane defaults
- [Content negotiation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation) between server and client
- Support for JSON ([RFC 8259](https://tools.ietf.org/html/rfc8259)) and CBOR ([RFC 7049](https://tools.ietf.org/html/rfc7049)) content types via the `Accept` header with the default config.
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/features/response-errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ The error functions are named like `Error{code}{name}` and accept a message and

## Error Model

Errors use [RFC 7807 Problem Details for HTTP APIs](https://tools.ietf.org/html/rfc7807) with a content type like `application/problem+json` and return a structure that looks like:
Errors use [RFC 9457 Problem Details for HTTP APIs](https://tools.ietf.org/html/rfc9457) with a content type like `application/problem+json` and return a structure that looks like:

```http title="HTTP Response"
HTTP/2.0 422 Unprocessable Entity
Expand Down Expand Up @@ -150,4 +150,4 @@ To change the default content type that is returned, you can also implement the
- [`huma.ContentTypeFilter`](https://pkg.go.dev/github.com/danielgtaylor/huma/v2#ContentTypeFilter) interface for custom content types
- External Links
- [HTTP Status Codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)
- [RFC 7807](https://tools.ietf.org/html/rfc7807) Problem Details for HTTP APIs
- [RFC 9457](https://tools.ietf.org/html/rfc9457) Problem Details for HTTP APIs
6 changes: 3 additions & 3 deletions error.go
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,8 @@ func (e *ErrorDetail) ErrorDetail() *ErrorDetail {
return e
}

// ErrorModel defines a basic error message model based on RFC 7807 Problem
// Details for HTTP APIs (https://datatracker.ietf.org/doc/html/rfc7807). It
// ErrorModel defines a basic error message model based on RFC 9457 Problem
// Details for HTTP APIs (https://datatracker.ietf.org/doc/html/rfc9457). It
// is augmented with an `errors` field of `huma.ErrorDetail` objects that
// can help provide exhaustive & descriptive errors.
//
Expand Down Expand Up @@ -122,7 +122,7 @@ func (e *ErrorModel) GetStatus() int {

// ContentType provides a filter to adjust response content types. This is
// used to ensure e.g. `application/problem+json` content types defined in
// RFC 7807 Problem Details for HTTP APIs are used in responses to clients.
// RFC 9457 Problem Details for HTTP APIs are used in responses to clients.
func (e *ErrorModel) ContentType(ct string) string {
if ct == "application/json" {
return "application/problem+json"
Expand Down

0 comments on commit bc86e7e

Please sign in to comment.