openapi

README

GoREST OpenAPI Plugin

OpenAPI documentation plugin for GoREST framework.

Installation

go get github.com/nicolasbonnici/gorest-openapi

Development Environment

To set up your development environment:

make install

This will:

• Install Go dependencies
• Install development tools (golangci-lint)
• Set up git hooks (pre-commit linting and tests)

Usage

import (
	"github.com/nicolasbonnici/gorest/pluginloader"
	openapiplugin "github.com/nicolasbonnici/gorest-openapi"
)

func init() {
	pluginloader.RegisterPluginFactory("openapi", openapiplugin.NewPlugin)
}

Configuration

Add to your gorest.yaml:

plugins:
  - name: openapi
    enabled: true
    config:
      # Required
      dtos_directory: "./dtos"  # Path to your DTOs directory

      # Optional API information (with defaults shown)
      title: "My API"                                    # default: "GoREST API"
      version: "1.0.0"                                   # default: "1.0.0"
      description: "My awesome API documentation"        # default: "Auto-generated REST API with full CRUD operations"

      # Optional pagination settings (with defaults shown)
      pagination_limit: 20      # default: 20
      pagination_max_limit: 100 # default: 100

      # Optional security settings
      hide_on_production: true  # default: true - disables /openapi endpoints when true

Minimal Configuration

plugins:
  - name: openapi
    enabled: true
    config:
      dtos_directory: "./dtos"

Development Environment Configuration

For development environments where you want to enable the OpenAPI endpoints:

plugins:
  - name: openapi
    enabled: true
    config:
      dtos_directory: "./dtos"
      hide_on_production: false  # Enable OpenAPI endpoints for development

Note: The server URL is automatically detected from incoming requests, so it works with any port your application runs on.

Features

• Auto-generated OpenAPI 3.0 specification
• Interactive API documentation UI at /openapi
• OpenAPI JSON schema at /openapi.json
• Dynamic schema generation from database
• Scalar API reference integration
• Production-ready security with hide_on_production flag (enabled by default)

Endpoints

• GET /openapi - Interactive API documentation UI
• GET /openapi.json - OpenAPI 3.0 JSON schema

---

Git Hooks

This directory contains git hooks for the GoREST plugin to maintain code quality.

Available Hooks

pre-commit

Runs before each commit to ensure code quality:

• Linting: Runs make lint to check code style and potential issues
• Tests: Runs make test to verify all tests pass

Installation

Automatic Installation

Run the install script from the project root:

./.githooks/install.sh

Manual Installation

Copy the hooks to your .git/hooks directory:

cp .githooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

---

License

MIT License - see LICENSE file for details

Documentation

Index

• func NewPlugin() plugin.Plugin
• type GeneratorConfig
• type OpenAPIPlugin
  • func (p *OpenAPIPlugin) Handler() fiber.Handler
  • func (p *OpenAPIPlugin) Initialize(cfg map[string]interface{}) error
  • func (p *OpenAPIPlugin) Name() string
  • func (p *OpenAPIPlugin) SetupEndpoints(router fiber.Router) error

Functions

func NewPlugin

func NewPlugin() plugin.Plugin

Types

type GeneratorConfig

type GeneratorConfig struct {
	DTOsDirectory      string
	PluginRegistry     *plugin.PluginRegistry
	PaginationLimit    int
	PaginationMaxLimit int
	ServerURL          string
	Title              string
	Version            string
	Description        string
}

type OpenAPIPlugin

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

func (*OpenAPIPlugin) Handler

func (p *OpenAPIPlugin) Handler() fiber.Handler

Handler returns a no-op middleware

func (*OpenAPIPlugin) Initialize

func (p *OpenAPIPlugin) Initialize(cfg map[string]interface{}) error

func (*OpenAPIPlugin) Name

func (p *OpenAPIPlugin) Name() string

func (*OpenAPIPlugin) SetupEndpoints

func (p *OpenAPIPlugin) SetupEndpoints(router fiber.Router) error

SetupEndpoints implements the EndpointSetup interface