Additional docs + normalize operation IDs (#974)

* Include docs warning for OpenAPIPath (#834)

* Replace spaces in OperationIDs with hyphens (#721)

* Add examples of who is using Huma

Author: wolveix

README.md

@@ -210,6 +210,10 @@ Official Go package documentation can always be found at https://pkg.go.dev/gith
 - [Bump.sh Deploying Docs from Huma](https://docs.bump.sh/guides/bump-sh-tutorials/huma/)
 - Mentioned in [Composable HTTP Handlers Using Generics](https://www.willem.dev/articles/generic-http-handlers/)
 
+# Who is using Huma?
+
+Huma is used by many companies and open-source projects. See the [Who is using Huma?](https://huma.rocks/why/#who-is-using-huma) page for a list!
+
 Be sure to star the project if you find it useful!
 
 <a href="https://star-history.com/#danielgtaylor/huma&Date">

README_CN.md

@@ -184,6 +184,10 @@ HTTP/1.1 200 OK
 - [Bump.sh 从 Huma 部署文档](https://docs.bump.sh/guides/bump-sh-tutorials/huma/)
 - [使用泛型的可组合 HTTP 处理程序](https://www.willem.dev/articles/generic-http-handlers/)中提到
 
+# 谁在使用 Huma？
+
+Huma 被许多公司和开源项目所使用。请参阅 [谁在使用 Huma？](https://huma.rocks/why/#who-is-using-huma) 页面查看列表！
+
 如果您觉得该项目有用，请务必为该项目加注星标！
 
 <a href="https://star-history.com/#danielgtaylor/huma&Date">

README_JA.md

@@ -235,6 +235,12 @@ HTTP/1.1 200 OK
 
 ---
 
+## Humaを使用しているプロジェクト
+
+Humaは多くの企業やオープンソースプロジェクトで使用されています。リストについては、[Humaを使用しているプロジェクト](https://huma.rocks/why/#who-is-using-huma)のページをご覧ください！
+
+---
+
 プロジェクトが役に立った場合はぜひスターをお願いします！
 
 <a href="https://star-history.com/#danielgtaylor/huma&Date">

api.go

@@ -187,7 +187,8 @@ type Config struct {
 
 	// OpenAPIPath is the path to the OpenAPI spec without extension. If set
 	// to `/openapi` it will allow clients to get `/openapi.json` or
-	// `/openapi.yaml`, for example.
+	// `/openapi.yaml`, for example. Note that some middleware like chi's
+	// `URLFormat` can interfere with these paths by stripping the extension.
 	OpenAPIPath string
 
 	// DocsPath is the path to the API documentation. If set to `/docs `, it will

docs/docs/features/api-docs.md

@@ -20,6 +20,10 @@ You can switch to other documentation renderers using `config.DocsRenderer`. The
 
     You can disable the built-in documentation by setting `config.DocsPath` to an empty string. This allows you to provide your own documentation renderer if you wish.
 
+!!! warning "Middleware Conflicts"
+
+    Some middleware can interfere with the documentation renderer's ability to fetch the OpenAPI spec. For example, [go-chi/chi](https://github.com/go-chi/chi)'s `middleware.URLFormat` will rewrite URLs that end in `.json` or `.yaml` (e.g. `/openapi.json` -> `/openapi`), which can lead to 404 errors for the spec. If you encounter this, consider disabling that middleware or configuring it to skip the OpenAPI and documentation paths.
+
 ## Customizing Documentation
 
 You can customize the generated documentation by providing your own renderer function to the API adapter or by using the underlying router directly.

docs/docs/features/operations.md

@@ -71,7 +71,9 @@ huma.Get(api, "/things/{thing-id}", func(ctx context.Context, input *YourInput)
 })
 ```
 
-In the example above, the generated operation ID is `get-things-by-thing-id` with a summary of `Get things by id`. To customize these, override `huma.GenerateOperationID(method, path string, response any)` for operation IDs and `huma.GenerateSummary(method, path string, response any)` for summaries.
+In the example above, the generated operation ID is `get-things-by-thing-id` with a summary of `Get things by id`. Note that any spaces in an operation ID will be automatically replaced with hyphens (e.g. `my operation` becomes `my-operation`) to ensure compatibility with various tools.
+
+To customize these, override `huma.GenerateOperationID(method, path string, response any)` for operation IDs and `huma.GenerateSummary(method, path string, response any)` for summaries.
 
 This makes it easy to get started, particularly if coming from other frameworks, and you can simply switch to using `huma.Register` if/when you need to set additional fields on the operation.
 

docs/docs/tutorial/client-sdks.md

@@ -168,6 +168,17 @@ Congratulations! You just learned:
 -   How to generate a Go SDK for your API
 -   How to build a client using the SDK to call the API
 
+## External Resources
+
+For a more in-depth real-world example, check out [How to build an API with Go and Huma](https://zuplo.com/blog/how-to-build-an-api-with-go-and-huma) on the Zuplo blog. It covers:
+
+-   Creating a new Huma project & defining some endpoints
+-   Setting up MongoDB
+-   Running the service
+-   Hosting our API
+-   Creating a project on Zuplo
+-   Setting up API key authentication
+
 ## Dive Deeper
 
 Want to learn more about OpenAPI tooling like SDK generators and how to use them? Check these out next:

docs/docs/why/index.md

@@ -96,3 +96,25 @@ Huma provides guardrails & automation to keep your team and your services runnin
 -   Supports automatic CLI & SDK generation
 
 [:material-arrow-right: Start the tutorial now](../tutorial/installation.md)
+
+## Who is using Huma?
+
+Huma is used by a variety of companies and projects, from large-scale production services handling millions of requests to community-driven open-source tools.
+
+### Production at Scale
+
+Huma powers critical services for some of the largest companies in the world:
+
+- **Corporate Adoption**: We see regular traffic and adoption from **FinTechs**, **Mercedes-Benz**, and many other global companies.
+- **Roblox**: The content catalog service uses Huma and handles over a **million requests a second** in production.
+- **Warner Bros. Discovery**: Used to run major live events and services including the **Olympics**, **March Madness**, **CNN**, and more.
+
+### Open Source Projects
+
+The following is a list of open-source projects using Huma. If you would like to see your project listed here, please [open a pull request](https://github.com/danielgtaylor/huma/pulls) or [issue](https://github.com/danielgtaylor/huma/issues) to request it!
+
+- [AvengeMedia - dgop](https://github.com/AvengeMedia/dgop)
+- [ckoliber - GoCRUD](https://github.com/ckoliber/gocrud)
+- [fy0 - CodeKanban](https://github.com/fy0/CodeKanban)
+- [Global Cyber Alliance - Domain Security Scanner](https://github.com/globalcyberalliance/domain-security-scanner)
+- [Mozilla AI - MCPD](https://github.com/mozilla-ai/mcpd)

openapi.go

@@ -6,6 +6,7 @@ import (
 	"maps"
 	"net/http"
 	"reflect"
+	"strings"
 	"time"
 
 	"github.com/danielgtaylor/huma/v2/yaml"
@@ -1501,7 +1502,14 @@ type OpenAPI struct {
 // properly added to the Paths map and will call any registered OnAddOperation
 // functions.
 func (o *OpenAPI) AddOperation(op *Operation) {
-	// Check this won't create a duplicate operation ID.
+	// Normalize spaces in operation ID as some tools (e.g., Stoplight) do not
+	// handle them correctly and may redirect or fail to render the operation.
+	op.OperationID = strings.ReplaceAll(op.OperationID, " ", "-")
+
+	if o.Paths == nil {
+		o.Paths = map[string]*PathItem{}
+	}
+
 	if op.OperationID != "" {
 		for _, pathItem := range o.Paths {
 			for _, existingOp := range []*Operation{
@@ -1515,10 +1523,6 @@ func (o *OpenAPI) AddOperation(op *Operation) {
 		}
 	}
 
-	if o.Paths == nil {
-		o.Paths = map[string]*PathItem{}
-	}
-
 	item := o.Paths[op.Path]
 	if item == nil {
 		item = &PathItem{}

openapi_test.go

@@ -283,3 +283,14 @@ func TestAddOperationForceUniqueOperationIDs(t *testing.T) {
 		})
 	})
 }
+
+func TestAddOperationNormalizeOperationIDs(t *testing.T) {
+	oapi := &huma.OpenAPI{}
+	oapi.AddOperation(&huma.Operation{
+		OperationID: "test with spaces",
+		Method:      http.MethodGet,
+		Path:        "/test",
+	})
+
+	assert.Equal(t, "test-with-spaces", oapi.Paths["/test"].Get.OperationID)
+}