oasis

README

Oasis

A simple library for building HTTP REST/RPC APIs in Go backed by OpenAPI.

Features

• OpenAPI definitions for your endpoints in Go code
• Swagger UI rendering using compiled OpenAPI document
• Step-by-step migration from raw handlers to documented ones

Example

Here is a basic hello world example with Oasis:

package main

import (
	"net/http"

	"github.com/evgenymarkov/oasis"
	"github.com/evgenymarkov/oasis/openapi3"
)

const (
	serverHost = "localhost"
	serverPort = "3000"
	serverAddr = serverHost + ":" + serverPort
)

func main() {
	// Create multiplexer
	mux := http.NewServeMux()

	// Create API wrapper
	api := oasis.NewAPI(
		mux,
		oasis.NewAPIConfig().
			SetDocumentPath("/api/openapi.json").
			SetSwaggerUIPath("/api").
			SetSwaggerUITitle("API Docs"),
		openapi3.NewDocument().
			SetTitle("Greeting API").
			SetVersion("1.0.0"),
	)

	// Register operations
	api.Get(
		"/greeting/{name}",
		GetGreetingHandler,
		GetGreetingOperation,
	)

	// Start handling incoming requests
	if startErr := http.ListenAndServe(serverAddr, mux); startErr != nil {
		panic(startErr)
	}
}

package main

import (
	"net/http"

	"github.com/evgenymarkov/oasis/openapi3"
)

var GetGreetingOperation = openapi3.NewOperation().
	SetOperationID("GetGreeting").
	SetSummary("Get a greeting")

func GetGreetingHandler(response http.ResponseWriter, _ *http.Request) {
	_, _ = response.Write([]byte("Hello, world!"))
}

Development

1. Install Go 1.22 to run tests.
2. Install Taskfile to run tasks.
3. Install golangci-lint to lint code.

Now you can use any commands from the Taskfile.yaml and edit code on your machine.

Documentation

Index

• type API
  • func NewAPI(mux *http.ServeMux, config *APIConfig, document *openapi3.Document) *API
  • func (a *API) Delete(pattern string, handler http.HandlerFunc, operation *openapi3.Operation)
  • func (a *API) Document() *openapi3.Document
  • func (a *API) Get(pattern string, handler http.HandlerFunc, operation *openapi3.Operation)
  • func (a *API) Head(pattern string, handler http.HandlerFunc, operation *openapi3.Operation)
  • func (a *API) Options(pattern string, handler http.HandlerFunc, operation *openapi3.Operation)
  • func (a *API) Patch(pattern string, handler http.HandlerFunc, operation *openapi3.Operation)
  • func (a *API) Post(pattern string, handler http.HandlerFunc, operation *openapi3.Operation)
  • func (a *API) Put(pattern string, handler http.HandlerFunc, operation *openapi3.Operation)
  • func (a *API) Trace(pattern string, handler http.HandlerFunc, operation *openapi3.Operation)
• type APIConfig
  • func NewAPIConfig() *APIConfig
  • func (c *APIConfig) SetDocumentPath(path string) *APIConfig
  • func (c *APIConfig) SetSwaggerUIPath(path string) *APIConfig
  • func (c *APIConfig) SetSwaggerUITitle(title string) *APIConfig

Types

type API

type API struct {
	// contains filtered or unexported fields
}

API struct is a wrapper on top of multiplexer for registering operations.

func NewAPI

func NewAPI(
	mux *http.ServeMux,
	config *APIConfig,
	document *openapi3.Document,
) *API

NewAPI method creates new API struct and fills it up.

func (*API) Delete

func (a *API) Delete(
	pattern string,
	handler http.HandlerFunc,
	operation *openapi3.Operation,
)

Delete method registers an handler for HTTP DELETE requests matching the pattern and updates operations table in OpenAPI document.

func (*API) Document

func (a *API) Document() *openapi3.Document

Document method returns pointer to serializable openapi3.Document. This document can be saved in the file system and used for code generation.

func (*API) Get

func (a *API) Get(
	pattern string,
	handler http.HandlerFunc,
	operation *openapi3.Operation,
)

Get method registers an handler for HTTP GET requests matching the pattern and updates operations table in OpenAPI document.

func (*API) Head

func (a *API) Head(
	pattern string,
	handler http.HandlerFunc,
	operation *openapi3.Operation,
)

Head method registers an handler for HTTP HEAD requests matching the pattern and updates operations table in OpenAPI document.

func (*API) Options

func (a *API) Options(
	pattern string,
	handler http.HandlerFunc,
	operation *openapi3.Operation,
)

Options method registers an handler for HTTP OPTIONS requests matching the pattern and updates operations table in OpenAPI document.

func (*API) Patch

func (a *API) Patch(
	pattern string,
	handler http.HandlerFunc,
	operation *openapi3.Operation,
)

Patch method registers an handler for HTTP PATCH requests matching the pattern and updates operations table in OpenAPI document.

func (*API) Post

func (a *API) Post(
	pattern string,
	handler http.HandlerFunc,
	operation *openapi3.Operation,
)

Post method registers an handler for HTTP POST requests matching the pattern and updates operations table in OpenAPI document.

func (*API) Put

func (a *API) Put(
	pattern string,
	handler http.HandlerFunc,
	operation *openapi3.Operation,
)

Put method registers an handler for HTTP PUT requests matching the pattern and updates operations table in OpenAPI document.

func (*API) Trace

func (a *API) Trace(
	pattern string,
	handler http.HandlerFunc,
	operation *openapi3.Operation,
)

Trace method registers an handler for HTTP TRACE requests matching the pattern and updates operations table in OpenAPI document.

type APIConfig

type APIConfig struct {
	// DocumentPath is the path to the API specification in JSON format.
	//
	// Default: "/api/openapi.json"
	DocumentPath string

	// SwaggerUIPath is the path to the API documentation UI.
	//
	// Default: "/api"
	SwaggerUIPath string

	// SwaggerUITitle is the title of API documentation UI page.
	//
	// Default: "Swagger UI"
	SwaggerUITitle string
}

APIConfig struct describes configuration options for API.

func NewAPIConfig

func NewAPIConfig() *APIConfig

NewAPIConfig method creates new APIConfig with default settings.

func (*APIConfig) SetDocumentPath

func (c *APIConfig) SetDocumentPath(path string) *APIConfig

SetDocumentPath method sets custom path for the API specification in JSON format.

func (*APIConfig) SetSwaggerUIPath

func (c *APIConfig) SetSwaggerUIPath(path string) *APIConfig

SetSwaggerUIPath method sets custom path for the API documentation UI.

func (*APIConfig) SetSwaggerUITitle

func (c *APIConfig) SetSwaggerUITitle(title string) *APIConfig

SetSwaggerUITitle method sets custom title of the API documentation UI page.