httprequest

type PathItem interface {
	// Add one or more tags to the path item.
	// Tags are used to group operations in the OpenAPI document.
	Tag(...string) PathItem

	// Get registers a GET handler with the given summary and operation options.
	Get(handler http.HandlerFunc, fn func(PathOperation)) PathItem

	// Put registers a PUT handler with the given summary and operation options.
	Put(handler http.HandlerFunc, fn func(PathOperation)) PathItem

	// Post registers a POST handler with the given summary and operation options.
	Post(handler http.HandlerFunc, fn func(PathOperation)) PathItem

	// Delete registers a DELETE handler with the given summary and operation options.
	Delete(handler http.HandlerFunc, fn func(PathOperation)) PathItem

	// Patch registers a PATCH handler with the given summary and operation options.
	Patch(handler http.HandlerFunc, fn func(PathOperation)) PathItem

	// Options registers an OPTIONS handler with the given summary and operation options.
	Options(handler http.HandlerFunc, fn func(PathOperation)) PathItem

	// Head registers a HEAD handler with the given summary and operation options.
	Head(handler http.HandlerFunc, fn func(PathOperation)) PathItem

	// Trace registers a TRACE handler with the given summary and operation options.
	Trace(handler http.HandlerFunc, fn func(PathOperation)) PathItem

	// Handler returns the http.HandlerFunc that handles the PathItem
	Handler() http.HandlerFunc

	// Spec returns the openapi.PathItem for a path with optional path parameters
	Spec(string, *jsonschema.Schema) *openapi.PathItem

	// WrapHandler wraps the handler for a specific HTTP method with middleware.
	// The method should be an uppercase HTTP method name (GET, POST, etc.).
	// If no handler is registered for the method, the call is a no-op.
	WrapHandler(method string, fn func(http.HandlerFunc) http.HandlerFunc)
}

type PathOperation interface {
	// Add one or more tags to the operation.
	Tags(...string) PathOperation

	// Set the summary for the operation.
	Summary(string) PathOperation

	// Set the description for the operation.
	Description(string) PathOperation

	// Set the query parameters for the operation from a JSON schema.
	Query(*jsonschema.Schema) PathOperation

	// Mark the operation as deprecated.
	Deprecated() PathOperation

	// Add a request body for the operation with the given content type and schema.
	// An optional description can be provided. If no content type is provided, "application/json" is used.
	RequestBody(schema *jsonschema.Schema, contentType ...string) PathOperation

	// Add a JSON response for the operation with the given status code and schema.
	// An optional description can be provided; if not, the default HTTP status text will be used.
	JSONResponse(status int, schema *jsonschema.Schema, description ...string) PathOperation

	// Add an error response for the operation with the given status code.
	// An optional description can be provided; if not, the default HTTP status text will be used.
	ErrorResponse(status int, description ...string) PathOperation

	// Return a response for the operation with the given status code and content type.
	// An optional description can be provided; if not, the default HTTP status text will be used.
	Response(status int, contentType string, description ...string) PathOperation
}