openapi

type Config struct {
	OpenAPIVersion  string                     // OpenAPI version, e.g., "3.1.0".
	Title           string                     // Title of the API.
	Version         string                     // Version of the API.
	Description     *string                    // Optional description of the API.
	Contact         *Contact                   // Contact information for the API.
	License         *License                   // License information for the API.
	TermsOfService  *string                    // Terms of service URL.
	Servers         []Server                   // List of API servers.
	SecuritySchemes map[string]*SecurityScheme // Security schemes available for the API.
	Tags            []Tag                      // Tags used to organize operations.
	ExternalDocs    *ExternalDocs              // Additional external documentation.

	ReflectorConfig *ReflectorConfig // Configuration for schema reflection.

	DocsPath    string     // Path where the documentation will be served.
	SpecPath    string     // Path for the OpenAPI specification JSON or YAML.
	CacheAge    *int       // Cache age for OpenAPI specification responses.
	DisableDocs bool       // If true, disables serving OpenAPI docs.
	Logger      Logger     // Logger for diagnostic output.
	PathParser  PathParser // Path parser for framework-specific path conversions.

	UIProvider              config.Provider           // UI provider for the OpenAPI documentation.
	SwaggerUIConfig         *config.SwaggerUI         // Configuration for embedded Swagger UI.
	StoplightElementsConfig *config.StoplightElements // Configuration for Stoplight Elements.
	ReDocConfig             *config.ReDoc             // Configuration for Redoc.
	ScalarConfig            *config.Scalar            // Configuration for Scalar.
	RapiDocConfig           *config.RapiDoc           // Configuration for RapiDoc.
}

type Contact struct {
	Name  string // Contact name.
	URL   string // Contact URL. Format: uri.
	Email string // Contact email. Format: email.

	// MapOfAnything holds vendor extensions. Keys must match `^x-`.
	MapOfAnything map[string]any
}

type ContentUnit struct {
	Structure  any
	HTTPStatus int

	ContentType string // ContentType specifies the MIME type of the content.

	IsDefault bool // IsDefault indicates if this content unit is the default response.

	Description string // Description provides a description for the content unit.

	Encoding map[string]string // Encoding maps property names to content types
}

type ExternalDocs struct {
	Description string // Description of the documentation.

	URL string // Required. Documentation URL. Format: uri.

	MapOfAnything map[string]any // Vendor extensions. Keys must match `^x-`.
}

type InterceptDefNameFunc func(t reflect.Type, defaultDefName string) string

type InterceptPropFunc func(params InterceptPropParams) error

type InterceptPropParams struct {
	Context        *jsonschema.ReflectContext // Reflection context.
	Path           []string                   // Path to the property.
	Name           string                     // Property name.
	Field          reflect.StructField        // Struct field being processed.
	PropertySchema *jsonschema.Schema         // Generated property schema.
	ParentSchema   *jsonschema.Schema         // Parent object schema.
	Processed      bool                       // True if the property was already processed.
}

type InterceptSchemaFunc func(params InterceptSchemaParams) (stop bool, err error)

type InterceptSchemaParams struct {
	Context   *jsonschema.ReflectContext // Reflection context.
	Value     reflect.Value              // Value being reflected.
	Schema    *jsonschema.Schema         // Generated schema.
	Processed bool                       // True if the schema was already processed.
}

type License struct {
	Name string // License name (required).

	Identifier string // SPDX identifier.
	URL        string // License URL. Format: uri.

	// MapOfAnything holds vendor extensions. Keys must match `^x-`.
	MapOfAnything map[string]any
}

type Logger interface {
	Printf(format string, v ...any)
}

type OAuthFlows struct {
	Implicit          *OAuthFlowsImplicit
	Password          *OAuthFlowsPassword
	ClientCredentials *OAuthFlowsClientCredentials
	AuthorizationCode *OAuthFlowsAuthorizationCode

	MapOfAnything map[string]any // Vendor extensions. Keys must match `^x-`.
}

type OAuthFlowsAuthorizationCode struct {
	AuthorizationURL string            // Required. Format: uri.
	TokenURL         string            // Required. Token URL. Format: uri.
	RefreshURL       *string           // Optional refresh URL. Format: uri.
	Scopes           map[string]string // Required. Available scopes.

	MapOfAnything map[string]any // Vendor extensions. Keys must match `^x-`.
}

type OAuthFlowsClientCredentials struct {
	TokenURL   string            // Required. Token URL. Format: uri.
	RefreshURL *string           // Optional refresh URL. Format: uri.
	Scopes     map[string]string // Required. Available scopes.

	MapOfAnything map[string]any // Vendor extensions. Keys must match `^x-`.
}

type OAuthFlowsImplicit struct {
	AuthorizationURL string            // Required. Format: uri.
	RefreshURL       *string           // Optional refresh URL. Format: uri.
	Scopes           map[string]string // Required. Available scopes.

	MapOfAnything map[string]any // Vendor extensions. Keys must match `^x-`.
}

type OAuthFlowsPassword struct {
	TokenURL   string            // Required. Token URL. Format: uri.
	RefreshURL *string           // Optional refresh URL. Format: uri.
	Scopes     map[string]string // Required. Available scopes.

	MapOfAnything map[string]any // Vendor extensions. Keys must match `^x-`.
}

type ParameterIn string

type PathParser interface {
	// Parse converts a framework-style path to OpenAPI path syntax.
	Parse(path string) (string, error)
}

type ReflectorConfig struct {
	InlineRefs           bool                   // If true, inline schema references instead of using components.
	RootRef              bool                   // If true, use a root reference for top-level schemas.
	RootNullable         bool                   // If true, allow root schemas to be nullable.
	StripDefNamePrefix   []string               // Prefixes to strip from generated definition names.
	InterceptDefNameFunc InterceptDefNameFunc   // Function to customize definition names.
	InterceptPropFunc    InterceptPropFunc      // Function to intercept property schema generation.
	InterceptSchemaFunc  InterceptSchemaFunc    // Function to intercept full schema generation.
	TypeMappings         []TypeMapping          // Custom type mappings for schema generation.
	ParameterTagMapping  map[ParameterIn]string // Custom struct tag mapping for parameters.
}

type SecurityScheme struct {
	Description *string                   // Optional description.
	APIKey      *SecuritySchemeAPIKey     // API key authentication scheme.
	HTTPBearer  *SecuritySchemeHTTPBearer // HTTP Bearer authentication scheme.
	OAuth2      *SecuritySchemeOAuth2     // OAuth2 authentication scheme.

	MapOfAnything map[string]any // Vendor extensions. Keys must match `^x-`.
}

type SecuritySchemeAPIKey struct {
	Name string                 // Required. Name of the header, query, or cookie parameter.
	In   SecuritySchemeAPIKeyIn // Required. Location of the API key.
}

type SecuritySchemeAPIKeyIn string

type SecuritySchemeHTTPBearer struct {
	Scheme       string  // Required. Must match pattern `^[Bb][Ee][Aa][Rr][Ee][Rr]$`.
	BearerFormat *string // Optional bearer format hint.
}

type SecuritySchemeOAuth2 struct {
	Flows OAuthFlows // Required. Supported OAuth2 flows.
}

type Server struct {
	URL string // Required. Server URL. Format: uri-reference.

	Description *string                   // Optional server description.
	Variables   map[string]ServerVariable // Server variables for URL templates.

	MapOfAnything map[string]any // Vendor extensions. Keys must match `^x-`.
}

type ServerVariable struct {
	Enum    []string // Allowed values.
	Default string   // Required. Default value.

	Description   string         // Variable description.
	MapOfAnything map[string]any // Vendor extensions. Keys must match `^x-`.
}

type Tag struct {
	Name          string         // Tag name (required).
	Description   string         // Tag description.
	ExternalDocs  *ExternalDocs  // Additional external documentation.
	MapOfAnything map[string]any // Vendor extensions. Keys must match `^x-`.
}

type TypeMapping struct {
	Src any // Source type.
	Dst any // Destination type.
}