goctl.nvim

A Neovim plugin for go-zero .api file support.

Features

• Syntax highlighting for .api files
• Format on save using goctl api format
• Go-to-definition, find references, and go-to-type-definition
• Auto-remove struct keyword from type definitions
• Code snippets (LuaSnip integration)
• Code generation command

Requirements

• Neovim >= 0.9.0
• goctl installed and in PATH
• (Optional) LuaSnip for snippets

Installation

lazy.nvim

{
  "fahmiauliarahman/goctl.nvim",
  ft = { "goctl", "api" },
  opts = {
    format_on_save = true,
    goctl_path = "goctl",
    enable_snippets = true,
    enable_keymaps = true,
    remove_struct_keyword = true,
  },
}

packer.nvim

use {
  "fahmiauliarahman/goctl.nvim",
  config = function()
    require("goctl").setup()
  end,
}

Configuration

Default configuration:

require("goctl").setup({
  -- Enable format on save
  format_on_save = true,
  -- Path to goctl binary
  goctl_path = "goctl",
  -- Enable snippets (requires LuaSnip)
  enable_snippets = true,
  -- Enable default keymaps (gd, gr, gy)
  enable_keymaps = true,
  -- Remove "struct" keyword from type definitions on format
  remove_struct_keyword = true,
})

Commands

Command	Description
:GoctlFormat	Format the current .api file
:GoctlGenerate	Generate Go code from the .api file

Keymaps

When enable_keymaps is true, the following keymaps are available in .api files:

Keymap	Description
gd	Go to definition
gr	Find references
gy	Go to type definition

Snippets

Available snippets (prefix → expansion):

Prefix	Description
info	API info block
service	Service definition
type / tys	Type/struct definition
handler	Route handler with doc
@doc	Doc annotation
@server	Server annotation
@handler	Handler annotation
get	GET endpoint
post	POST endpoint
put	PUT endpoint
delete	DELETE endpoint
patch	PATCH endpoint
json	JSON tag
path	Path tag
form	Form tag
jwt	JWT middleware
group	Route group with prefix
im	Import statement

Example .api file

info(
    title: User API
    desc: User management API
    author: Your Name
    email: [email protected]
    version: 1.0
)

type (
    LoginRequest {
        Username string `json:"username"`
        Password string `json:"password"`
    }

    LoginResponse {
        Token string `json:"token"`
    }
)

@server(
    prefix: /api/v1
)
service user-api {
    @doc(
        summary: User login
    )
    @handler LoginHandler
    post /login(LoginRequest) returns(LoginResponse)
}

License

MIT