irisopenapi

README

irisopenapi

A lightweight adapter for the Iris web framework that automatically generates OpenAPI 3.x specifications from your routes using oaswrap/spec.

Installation

go get github.com/oaswrap/spec/adapter/irisopenapi

Quick Start

package main

import (
	"github.com/kataras/iris/v12"
	"github.com/oaswrap/spec/adapter/irisopenapi"
	"github.com/oaswrap/spec/option"
)

func main() {
	app := iris.New()
	r := irisopenapi.NewRouter(app,
		option.WithTitle("My API"),
		option.WithVersion("1.0.0"),
	)

	r.Get("/ping", func(ctx iris.Context) {
		_ = ctx.JSON(map[string]string{"message": "pong"})
	}).With(
		option.OperationID("ping"),
		option.Response(200, new(struct {
			Message string `json:"message"`
		})),
	)

	_ = app.Listen(":8080")
}

Built-in Endpoints

• /docs for interactive API docs UI.
• /docs/openapi.yaml for raw OpenAPI YAML.

Use option.WithDisableDocs(true) to disable docs endpoints.

Documentation

Index

• type Generator
  • func NewGenerator(party iris.Party, opts ...option.OpenAPIOption) Generator
  • func NewRouter(party iris.Party, opts ...option.OpenAPIOption) Generator
• type Route
• type Router

Types

type Generator

type Generator interface {
	Router

	// Validate checks if the OpenAPI specification is valid.
	Validate() error

	// ValidateReport validates the schema and returns all findings.
	ValidateReport() error

	// GenerateSchema generates the OpenAPI schema.
	// Defaults to YAML. Pass "json" to generate JSON.
	GenerateSchema(format ...string) ([]byte, error)

	// MarshalYAML marshals the OpenAPI schema to YAML.
	MarshalYAML() ([]byte, error)

	// MarshalJSON marshals the OpenAPI schema to JSON.
	MarshalJSON() ([]byte, error)

	// WriteSchemaTo writes the schema to the given file.
	// The format is inferred from the file extension.
	WriteSchemaTo(filepath string) error
}

Generator defines an Iris-compatible OpenAPI generator.

func NewGenerator

func NewGenerator(party iris.Party, opts ...option.OpenAPIOption) Generator

NewGenerator creates a new OpenAPI generator with the provided Iris party and options.

func NewRouter

func NewRouter(party iris.Party, opts ...option.OpenAPIOption) Generator

NewRouter creates a new OpenAPI router with the provided Iris party and options.

type Route

type Route interface {
	// Method returns the HTTP method (GET, POST, etc.).
	Method() string

	// Path returns the route path.
	Path() string

	// Name returns the route name.
	Name() string

	// With applies OpenAPI operation options to this route.
	With(opts ...option.OperationOption) Route
}

Route represents a single Iris route with OpenAPI metadata.

type Router

type Router interface {
	// Handle registers a new route with the given method, path, and handlers.
	Handle(method string, path string, handlers ...context.Handler) Route

	// Get registers a new GET route.
	Get(path string, handlers ...context.Handler) Route

	// Post registers a new POST route.
	Post(path string, handlers ...context.Handler) Route

	// Put registers a new PUT route.
	Put(path string, handlers ...context.Handler) Route

	// Delete registers a new DELETE route.
	Delete(path string, handlers ...context.Handler) Route

	// Patch registers a new PATCH route.
	Patch(path string, handlers ...context.Handler) Route

	// Head registers a new HEAD route.
	Head(path string, handlers ...context.Handler) Route

	// Options registers a new OPTIONS route.
	Options(path string, handlers ...context.Handler) Route

	// Trace registers a new TRACE route.
	Trace(path string, handlers ...context.Handler) Route

	// Connect registers a new CONNECT route.
	// Connect operations are emitted only for OpenAPI 3.2.0.
	Connect(path string, handlers ...context.Handler) Route

	// Party creates a new sub-party with the given prefix and middleware.
	Party(prefix string, handlers ...context.Handler) Router

	// Use adds middleware.
	Use(handlers ...context.Handler) Router

	// With applies OpenAPI group options to this router.
	With(opts ...option.GroupOption) Router
}

Router defines an OpenAPI-aware Iris router.