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

• Declarative interface on top of your router:
  • Operation & model documentation
  • Request params (path, query, or header)
  • Request body
  • Responses (including errors)
  • Response headers
• JSON Errors using RFC9457 and application/problem+json by default (but can be changed)
• Per-operation request size limits with sane defaults
• Content negotiation between server and client
  • Support for JSON (RFC 8259) and CBOR (RFC 7049) content types via the Accept header with the default config.
• Conditional requests support, e.g. If-Match or If-Unmodified-Since header utilities.
• Optional automatic generation of PATCH operations that support:
  • RFC 7386 JSON Merge Patch
  • RFC 6902 JSON Patch
  • Shorthand patches
• Annotated Go types for input and output models
  • Generates JSON Schema from Go types
  • Static typing for path/query/header params, bodies, response headers, etc.
  • Automatic input model validation & error handling
• Documentation generation using Stoplight Elements
• Optional CLI built-in, configured via arguments or environment variables
  • Set via e.g. -p 8000, --port=8000, or SERVICE_PORT=8000
  • Startup actions & graceful shutdown built-in
• Generates OpenAPI for access to a rich ecosystem of tools
  • Mocks with API Sprout or Prism
  • SDKs with OpenAPI Generator or oapi-codegen
  • CLI with Restish
  • And plenty more
• Generates JSON Schema for each resource using optional describedby link relation headers as well as optional $schema properties in returned objects that integrate into editors for validation & completion.

Install via go get. Note that Go 1.22 or newer is required.

go get -u github.com/evgenymarkov/oasis

Here is a complete basic hello world example in Oasis, that shows how to initialize a Oasis app complete with CLI, declare a resource operation, and define its handler function.

package main

import (
	"context"
	"fmt"
	"net/http"

	"github.com/evgenymarkov/oasis"
	"github.com/evgenymarkov/oasis/adapters/chioasis"
	"github.com/go-chi/chi/v5"
)

// Options for the CLI.
type Options struct {
	Port int `help:"Port to listen on" short:"p" default:"8888"`
}

// GreetingInput represents the greeting operation request.
type GreetingInput struct {
	Name string `path:"name" maxLength:"30" example:"world" doc:"Name to greet"`
}

// GreetingOutput represents the greeting operation response.
type GreetingOutput struct {
	Body struct {
		Message string `json:"message" example:"Hello, world!" doc:"Greeting message"`
	}
}

func main() {
	// Create a CLI app which takes a port option.
	cli := oasis.NewCLI(func(hooks oasis.Hooks, options *Options) {
		// Create a new router & API
		router := chi.NewMux()
		api := chioasis.New(router, oasis.DefaultConfig("My API", "1.0.0"))

		// Register GET /greeting/{name}
		oasis.Register(api, oasis.Operation{
			OperationID: "get-greeting",
			Summary:     "Get a greeting",
			Method:      http.MethodGet,
			Path:        "/greeting/{name}",
		}, func(ctx context.Context, input *GreetingInput) (*GreetingOutput, error) {
			resp := &GreetingOutput{}
			resp.Body.Message = fmt.Sprintf("Hello, %s!", input.Name)
			return resp, nil
		})

		// Tell the CLI how to start your router.
		hooks.OnStart(func() {
			http.ListenAndServe(fmt.Sprintf(":%d", options.Port), router)
		})
	})

	// Run the CLI. When passed no commands, it starts the server.
	cli.Run()
}

You can test it with go run greet.go (optionally pass --port to change the default) and make a sample request using Restish (or curl):

# Get the message from the server
$ restish :8888/greeting/world
HTTP/1.1 200 OK
...
{
	$schema: "http://localhost:8888/schemas/GreetingOutputBody.json",
	message: "Hello, world!"
}

Even though the example is tiny you can also see some generated documentation at http://localhost:8888/docs. The generated OpenAPI is available at http://localhost:8888/openapi.json or http://localhost:8888/openapi.yaml.