diag

Documentation

Overview

Package diag provides diagnostic types for OpenAPI spec generation.

This package defines warning types and codes used throughout the openapi package. Warnings are informational, non-fatal issues that don't prevent spec generation.

Basic Usage

Most users don't need to import this package directly - warning types are re-exported from the main openapi package:

import "rivaas.dev/openapi"

if err := api.AddOperation(ops...); err != nil {
    log.Fatal(err)
}
result, _ := api.Spec(ctx)
if len(result.Warnings) > 0 {
    fmt.Printf("Generated with %d warnings\n", len(result.Warnings))
}

Type-Safe Warning Checks

Import this package for type-safe warning code comparisons:

import (
    "rivaas.dev/openapi"
    "rivaas.dev/openapi/diag"
)

if err := api.AddOperation(ops...); err != nil {
    log.Fatal(err)
}
result, _ := api.Spec(ctx)

// Type-safe check with IDE autocomplete
if result.Warnings.Has(diag.WarnDownlevelWebhooks) {
    log.Warn("webhooks were dropped for OpenAPI 3.0")
}

// Filter by category
downlevelWarnings := result.Warnings.FilterCategory(diag.CategoryDownlevel)

Warning Categories

Warnings are grouped into categories:

• CategoryDownlevel: Features lost when converting 3.1 → 3.0
• CategoryDeprecation: Using deprecated OpenAPI features

Validation issues are ERRORS, not warnings.

Package diag provides diagnostic types for OpenAPI spec generation. This package contains warning types and codes that are used throughout the openapi package and its subpackages.

Index

• type Warning
  • func NewWarning(code WarningCode, path, message string) Warning
• type WarningCategory
  • func (c WarningCategory) String() string
• type WarningCode
  • func (c WarningCode) Category() WarningCategory
  • func (c WarningCode) String() string
• type Warnings
  • func (ws Warnings) Codes() []WarningCode
  • func (ws Warnings) Counts() map[WarningCategory]int
  • func (ws Warnings) Each(fn func(Warning))
  • func (ws Warnings) Exclude(codes ...WarningCode) Warnings
  • func (ws Warnings) Filter(codes ...WarningCode) Warnings
  • func (ws Warnings) FilterCategory(cat WarningCategory) Warnings
  • func (ws Warnings) Has(code WarningCode) bool
  • func (ws Warnings) HasAny(codes ...WarningCode) bool
  • func (ws Warnings) HasCategory(cat WarningCategory) bool
  • func (ws Warnings) String() string

Types

type Warning

type Warning interface {
	// Code returns the warning identifier.
	// Compare with Warn* constants for type-safe checks.
	Code() WarningCode

	// Path returns the JSON pointer to the affected spec element.
	// Example: "#/webhooks", "#/info/summary"
	Path() string

	// Message returns a human-readable description.
	Message() string

	// Category returns the warning's category for grouping.
	Category() WarningCategory

	// String returns a formatted representation.
	String() string
}

Warning represents an informational, non-fatal issue during spec generation.

Warnings are ADVISORY ONLY and never break execution. Use errors for issues that must stop the process.

Common scenarios that produce warnings:

• Targeting OpenAPI 3.0 when using 3.1-only features (downlevel)
• Using deprecated API features

func NewWarning

func NewWarning(code WarningCode, path, message string) Warning

NewWarning creates a new Warning instance. This is the primary way to create warnings from internal packages.

type WarningCategory

type WarningCategory string

WarningCategory groups related warning types.

const (
	// CategoryUnknown for unrecognized warning codes.
	CategoryUnknown WarningCategory = "unknown"

	// CategoryDownlevel for 3.1 → 3.0 conversion feature losses.
	// The spec is still valid, just with reduced functionality.
	CategoryDownlevel WarningCategory = "downlevel"

	// CategoryDeprecation for deprecated feature usage.
	// The feature still works but is discouraged.
	CategoryDeprecation WarningCategory = "deprecation"
)

func (WarningCategory) String

func (c WarningCategory) String() string

String returns the category as a string.

type WarningCode

type WarningCode string

WarningCode identifies a specific warning type. Use the Warn* constants for type-safe comparisons.

const (
	// WarnDownlevelWebhooks indicates webhooks were dropped (3.0 doesn't support them).
	WarnDownlevelWebhooks WarningCode = "DOWNLEVEL_WEBHOOKS"

	// WarnDownlevelInfoSummary indicates info.summary was dropped (3.0 doesn't support it).
	WarnDownlevelInfoSummary WarningCode = "DOWNLEVEL_INFO_SUMMARY"

	// WarnDownlevelLicenseIdentifier indicates license.identifier was dropped.
	WarnDownlevelLicenseIdentifier WarningCode = "DOWNLEVEL_LICENSE_IDENTIFIER"

	// WarnDownlevelMutualTLS indicates mutualTLS security scheme was dropped.
	WarnDownlevelMutualTLS WarningCode = "DOWNLEVEL_MUTUAL_TLS"

	// WarnDownlevelConstToEnum indicates JSON Schema const was converted to enum.
	WarnDownlevelConstToEnum WarningCode = "DOWNLEVEL_CONST_TO_ENUM"

	// WarnDownlevelConstToEnumConflict indicates const conflicted with existing enum.
	WarnDownlevelConstToEnumConflict WarningCode = "DOWNLEVEL_CONST_TO_ENUM_CONFLICT"

	// WarnDownlevelPathItems indicates $ref in pathItems was expanded.
	WarnDownlevelPathItems WarningCode = "DOWNLEVEL_PATH_ITEMS"

	// WarnDownlevelPatternProperties indicates patternProperties was dropped.
	WarnDownlevelPatternProperties WarningCode = "DOWNLEVEL_PATTERN_PROPERTIES"

	// WarnDownlevelUnevaluatedProperties indicates unevaluatedProperties was dropped.
	WarnDownlevelUnevaluatedProperties WarningCode = "DOWNLEVEL_UNEVALUATED_PROPERTIES"

	// WarnDownlevelContentEncoding indicates contentEncoding was dropped.
	WarnDownlevelContentEncoding WarningCode = "DOWNLEVEL_CONTENT_ENCODING"

	// WarnDownlevelContentMediaType indicates contentMediaType was dropped.
	WarnDownlevelContentMediaType WarningCode = "DOWNLEVEL_CONTENT_MEDIA_TYPE"

	// WarnDownlevelMultipleExamples indicates multiple examples were collapsed to one.
	WarnDownlevelMultipleExamples WarningCode = "DOWNLEVEL_MULTIPLE_EXAMPLES"
)

Downlevel Warnings (3.1 → 3.0 feature losses)

const (
	// WarnDeprecationExampleSingular indicates using deprecated singular example field.
	WarnDeprecationExampleSingular WarningCode = "DEPRECATION_EXAMPLE_SINGULAR"
)

Deprecation Warnings (using deprecated features)

func (WarningCode) Category

func (c WarningCode) Category() WarningCategory

Category returns the code's category.

func (WarningCode) String

func (c WarningCode) String() string

String returns the code as a string.

type Warnings

type Warnings []Warning

Warnings is a collection of Warning with helper methods. Warnings are informational and never break execution.

func (Warnings) Codes

func (ws Warnings) Codes() []WarningCode

Codes returns all unique warning codes in this collection.

func (Warnings) Counts

func (ws Warnings) Counts() map[WarningCategory]int

Counts returns warning counts grouped by category.

func (Warnings) Each

func (ws Warnings) Each(fn func(Warning))

Each calls fn for each warning.

func (Warnings) Exclude

func (ws Warnings) Exclude(codes ...WarningCode) Warnings

Exclude returns warnings NOT matching the given codes.

func (Warnings) Filter

func (ws Warnings) Filter(codes ...WarningCode) Warnings

Filter returns warnings matching the given codes.

func (Warnings) FilterCategory

func (ws Warnings) FilterCategory(cat WarningCategory) Warnings

FilterCategory returns warnings in the given category.

func (Warnings) Has

func (ws Warnings) Has(code WarningCode) bool

Has returns true if any warning matches the given code.

func (Warnings) HasAny

func (ws Warnings) HasAny(codes ...WarningCode) bool

HasAny returns true if any warning matches any given code.

func (Warnings) HasCategory

func (ws Warnings) HasCategory(cat WarningCategory) bool

HasCategory returns true if any warning is in the given category.

func (Warnings) String

func (ws Warnings) String() string

String returns a formatted string of all warnings.