Skip to content

Getting Started

Jump to bottom
MeGaNeKo edited this page Mar 20, 2026 · 2 revisions

Getting Started

Installation

Requires Go 1.25 or later.

go get github.com/MeGaNeKoS/neoma

All adapters (Chi, Echo, Gin, Fiber, stdlib) and their router dependencies are included.

Hello World

package main

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

	"github.com/MeGaNeKoS/neoma/adapters/neomachi/v5"
	"github.com/MeGaNeKoS/neoma/core"
	"github.com/MeGaNeKoS/neoma/neoma"
	"github.com/go-chi/chi/v5"
)

// GreetInput defines the path parameter.
type GreetInput struct {
	Name string `path:"name" doc:"Name to greet" example:"world"`
}

// GreetOutput defines the response body.
type GreetOutput struct {
	Body struct {
		Message string `json:"message" example:"Hello, world!" doc:"Greeting message"`
	}
}

func main() {
	// Create a Chi router and Neoma adapter.
	router := chi.NewMux()
	adapter := neomachi.NewAdapter(router)

	// Create the API with default configuration.
	config := neoma.DefaultConfig("My API", "1.0.0")
	api := neoma.NewAPI(config, adapter)

	// Register a GET endpoint.
	neoma.Get(api, "/greet/{name}",
		func(ctx context.Context, input *GreetInput) (*GreetOutput, error) {
			resp := &GreetOutput{}
			resp.Body.Message = fmt.Sprintf("Hello, %s!", input.Name)
			return resp, nil
		},
	)

	// Start the server.
	fmt.Println("Listening on :8080")
	log.Fatal(http.ListenAndServe(":8080", router))
}

Note that both core and neoma are imported. Types like Config and Operation come from core; registration functions like NewAPI, Get, and Register come from neoma.

Running and Testing

Start the server:

go run main.go

Test with curl:

# Call the greeting endpoint
curl http://localhost:8080/greet/world
# {"message":"Hello, world!"}

# Fetch the OpenAPI spec
curl http://localhost:8080/openapi.json

# View interactive API docs in a browser
# http://localhost:8080/public/docs

The default docs provider is Scalar. See Configuration to switch to Stoplight Elements or Swagger UI.

Using neoma.Register Directly

For full control over operation metadata, use neoma.Register instead of the convenience helpers:

neoma.Register(api, core.Operation{
	OperationID: "greet-user",
	Method:      http.MethodGet,
	Path:        "/greet/{name}",
	Summary:     "Greet a user",
	Description: "Returns a personalized greeting.",
	Tags:        []string{"Greetings"},
}, func(ctx context.Context, input *GreetInput) (*GreetOutput, error) {
	resp := &GreetOutput{}
	resp.Body.Message = fmt.Sprintf("Hello, %s!", input.Name)
	return resp, nil
})

Next Steps

Clone this wiki locally