Skip to content

Configuration & Open API#

Huma 会自动生成兼容 Open API 3.1 的 JSON/YAML 规范并提供渲染后的文档。默认情况下，API 中注册的每个操作都会包含在规范中。操作的输入和输出用于生成请求和响应参数 / 架构。

huma.Config 控制 OpenAPI、文档和架构的可用位置。默认配置分别使用 /openapi、/docs 和 /schemas。您可以根据需要更改这些路径，或者通过留空完全禁用它们。OpenAPI 规范支持多个版本（以更好地支持旧工具），并提供 JSON 或 YAML 格式：

您可能希望自定义生成的 Open API 规范。在 Huma v2 中，您可以完全访问并在 API 配置或注册操作时根据需要修改它。例如，要设置然后使用安全方案：

code.go
config := huma.DefaultConfig("My API", "1.0.0")
config.Components.SecuritySchemes = map[string]*huma.SecurityScheme{
		"bearer": {
			Type: "http",
			Scheme: "bearer",
			BearerFormat: "JWT",
		},
	}
api := humachi.New(router, config)

huma.Register(api, huma.Operation{
	OperationID: "get-greeting",
	Method:      http.MethodGet,
	Path:        "/greeting/{name}",
	Summary:     "Get a greeting",
	Security: []map[string][]string{
		{"bearer": {}},
	},
}, func(ctx context.Context, input *GreetingInput) (*GreetingOutput, error) {
	// ...
})

Spec

有关可以设置的所有内容及其预期使用方式，请参阅 OpenAPI 3.1 规范 和 Huma 的 OpenAPI 结构体。

OpenAPI Settings Composition#

因为您可以完全访问 OpenAPI 规范，您可以根据需要组合它，并编写便利函数来使事情更简单。上述示例可以更易读：

code.go
config := huma.DefaultConfig("My API", "1.0.0")
config = withBearerAuthScheme(config)

api := humachi.New(router, config)

huma.Register(api, withBearerAuth(huma.Operation{
	OperationID: "get-greeting",
	Method:      http.MethodGet,
	Path:        "/greeting/{name}",
	Summary:     "Get a greeting",
}), func(ctx context.Context, input *GreetingInput) (*GreetingOutput, error) {
	// ...
})

您可以根据喜好设置它。即使 huma.Register 函数也可以被您的组织包装或替换，以确保所有操作都使用相同的设置进行注册。

Custom OpenAPI Extensions#

支持通过大多数 OpenAPI 结构上的 Extensions 字段进行自定义 OpenAPI 扩展：

code.go
config := huma.DefaultConfig("My API", "1.0.0")
config.Extensions = map[string]any{
	"my-extension": "my-value",
}

Extensions 映射中的任何内容在序列化期间都会被展平，以便其字段与 OpenAPI 规范中的 Extensions 同级。例如，上述内容将导致：

openapi.json
{
	"openapi": "3.1.0",
	"info": {
		"title": "My API",
		"version": "1.0.0"
	},
	"my-extension": "my-value"
}

Dive Deeper#