Fizz

The markdown.Builder distinguishes between two types of elements:

1. Block elements: These are concatenated to the underlying builder buffer. They typically represent structural components like headers, paragraphs, or lists.
2. Inline elements: These are returned directly as strings and are intended to be used within other elements (like inside a paragraph or a list item).

Block Elements

• Headers: H1, H2, H3, H4, H5, H6
• Paragraph: P
• Line: Line (similar to a paragraph but without a trailing line break)
• Line break: BR
• Blockquote: Blockquote
• Horizontal rule: HR
• Code: Code
• Lists: BulletedList, NumberedList (use builder.Block().NumberedList(...) for nested lists)

Inline Elements

• Alternative titles: AltH1, AltH2
• Emphasis: Emphasis, Italic
• Strong emphasis: StrongEmphasis, Bold
• Combined emphasis: StrongEmphasis
• Strikethrough: Strikethrough
• Code: InlineCode
• Link: Link
• Image: Image

The tonic subpackage provides a way to consolidate path, query, header, and body parameters into a single input object. This removes boilerplate code for retrieving and validating parameters. The OpenAPI generator uses the input/output types of a tonic-wrapped handler to document the operation in the specification.

To wrap a handler, use tonic.Handler. The handler must follow one of these signatures:

• func(*gin.Context, [input object ptr]) ([output object], error)
• func(*gin.Context) error (minimal signature)

Critical Requirement: The input object MUST always be a pointer to a struct, otherwise the tonic wrapping will panic at runtime.

// Example of a tonic-wrapped handler
func MyHandler(c *gin.Context, input *MyInput) (*MyOutput, error) {
    return &MyOutput{Message: "Hello"}, nil
}

// Registering it with Gin and Fizz
fizz.GET("/foo", tonic.Handler(MyHandler, 200))

Fizz provides wrappers for standard HTTP methods (GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD).

To ensure your API is correctly documented in the generated OpenAPI specification, exactly one of the handlers registered for an operation must be wrapped with tonic.Handler.

While you can pass multiple standard gin.HandlerFunc middlewares, the OpenAPI generator relies on the input/output types of the tonic.Handler to build the specification. If you only register standard Gin handlers, the operation will be ignored by the OpenAPI generator.

// BarHandler is a standard middleware
func BarHandler(c *gin.Context) { ... }

// FooHandler defines the input (*Foo) and output (*Bar) for OpenAPI
func FooHandler(*gin.Context, *Foo) (*Bar, error) { ... }

fizz := fizz.New()
// Registering BarHandler as middleware and FooHandler via tonic.Handler
fizz.GET("/foo/bar", nil, BarHandler, tonic.Handler(FooHandler, 200))

If your API is hosted on a different domain or uses a path prefix not included in the spec, use f.Generator().SetServers to declare server information.

To handle authentication, use f.Generator().SetSecuritySchemes to define global security schemes. These schemes are available to all operations by default, but you can override them on a per-operation basis using the fizz.Security() function.

f := fizz.New()

// Set server information
f.Generator().SetServers([]*openapi.Server{
   {
      Description: "Fruits Market - production",
      URL:         "https://example.org/api/1.0",
   },
})

// Set global security schemes
f.Generator().SetSecuritySchemes(map[string]*openapi.SecuritySchemeOrRef{
   "apiToken": {
      SecurityScheme: &openapi.SecurityScheme{
         Type: "apiKey",
         In:   "header",
         Name: "x-api-token",
      },
   },
})

// Override security for a specific operation
fizz.Security(&openapi.SecurityRequirement{
   "apiToken": []string{},
})

To manually control how a type is represented in the OpenAPI schema (instead of relying on reflection), you can use several approaches:

1. Implement DataType interface: Define Type() string and Format() string to control the schema output (e.g., representing a struct as a string with a uuid format).
2. Implement Nullable interface: Define Nullable() bool to override the nullable property.
3. Use OverrideDataType: Use f.Generator().OverrideDataType(reflect.TypeOf(T{}), "type", "format") for the highest precedence override.

Warning: Like openapi.Typer, do not rely on method receivers for state, as they are called on new instances created via reflection.

// Implementing DataType for a custom UUID type
type UUIDv4 struct { ... }

func (*UUIDv4) Format() string { return "uuid" }
func (*UUIDv4) Type() string { return "string" }

// Implementing Nullable
func (NullString) Nullable() bool { return true }

// Manual override with highest precedence
fizz.Generator().OverrideDataType(reflect.TypeOf(&UUIDv4{}), "string", "uuid")