trende-jp / go-httpdoc

Golang package for generating API documentation from httptest. See example output

go-httpdoc

go-httpdoc is a Golang package to generate API documentation from httptest test cases.

It provides a simple http middleware which records http requests and responses from tests and generates documentation automatically in markdown format. See Sample Documentation. It also provides a way to validate values are equal to what you expect with annotation (e.g., you can add a description for headers, params or response fields). If you write proper tests, it will generate usable documentation (namely, it forces you to write good tests).

Not only JSON request and response but it also supports protocol buffer. See Sample ProtoBuf Documentation).

See usage and example in GoDoc.

NOTE: This package is experimental and may make backward-incompatible changes.

Prerequisites

go-httpdoc requires Go 1.7 or later.

Install

Use go get:

$ go get -u go.mercari.io/go-httpdoc

Usage

All usage are described in GoDoc.

To generate documentation, set the following env var:

$ export HTTPDOC=1

Reference

The original idea came from r7kamura/autodoc (rack middleware).

For struct inspection in validator, it uses tenntenn/gpath package.