apidocgen

English | 简体中文

apidocgen is a tool for Go to generate apis markdown docs and mocks.

Install

go install github.com/alovn/apidocgen@latest

Cli

$ apidocgen --help
apidocgen is a tool for Go to generate apis markdown docs and mocks. For example:

apidocgen --dir= --excludes= --output= --output-index= --template= --single --gen-mocks
apidocgen --mock --mock-listen=:8001
apidocgen mock --data= --listen=

Usage:
  apidocgen [flags]
  apidocgen [command]

Available Commands:
  help        Help about any command
  mock        
  version     print version

Flags:
      --dir string            Search apis dir, comma separated (default ".")
      --excludes string       Exclude directories and files when searching, comma separated
      --gen-mocks             Is generate the mock files
  -h, --help                  help for apidocgen
      --mock-listen string    Mock Server listen address (default "localhost:8001")
      --mock                  Serve a mock server
      --output string         Generate markdown files dir (default "./docs/")
      --output-index string   Generate index file name
      --single                Is generate a single doc
      --template string       Template name or custom template directory, built-in includes markdown and apidocs

Use "apidocgen [command] --help" for more information about a command.

Template

The built-in templates include markdown and apidocs, default is markdown.

The template apidocs is the template for generate website apidocs.

You can also use the custom template:

apidocgen \
    --dir=svc-user,common \
    --template=/Users/xxx/workspace/apidocs/custom-template-direcoty \
    --output=./docs

How to use

apidocgen supported any web frameworks. here are an example using bytego.

1. Add API annotations in main.go code:

   //@title UserService
   //@service svc-user
   //@version 1.0.1
   //@desc the api about users
   //@baseurl /user
   func main() {
       r := bytego.New()
       c := controller.NewController()
       //@group account
       //@title Account
       //@desc account register and login
       account := r.Group("/account")
       {
           account.POST("/register", c.Register)
           account.POST("/login", c.Login)
       }
       _ = r.Run(":8000")
   }

2. Add API annotations in httpHandler.

   //@title AccountLogin
   //@api POST /account/login
   //@group account
   //@accept json
   //@format json
   //@request LoginRequest
   //@response 200 common.Response{code=0,msg="success",data=LoginResponse} "success description" //mock
   //@response 200 common.Response{code=10020,msg="password_error"} "error description"
   //@author alovn
   func (c *Controller) Login(c *bytego.Ctx) {
       //bind LoginRequest
       res := common.NewResponse(0, "success", &LoginResponse{
           WelcomeMsg: "welcome",
       })
       c.JSON(http.StatusOK, res)
   }

3. Execute apidocgen.

   apidocgen

   The markdown files will be generated in ./docs.

Examples

Some examples and generated markdown docs are here: apidocgen/examples.

An online generated api docs site: https://apidocgen.netlify.app/

Comments(annotations)

annotation	description	example
service	Required, the service's identification	@service svc-user
baseurl	The base url of api	@baseurl /
group	The group of service, add it at api comment or at the head of file comment.	@group account
title	The title of service, group and api	@title UserService
desc	The description of service, group and api	@desc xxx
api	The http api handler	@api POST /account/register
order	Sort groups and apis	@order 1
author	The author of api	@author alovn
version	The version of service or api	@version 1.0.1
accept	The request format, support json/xml	@accept json
format	The response format, support json/xml	@format json
request	The request body	@request LoginRequest
response	The response body, [http code] [data type]	@response 200 LoginResponse
success	As same as response	@success 200 LoginResponse
failure	As same as response	@failure 200 LoginResponse
param	The path parameter of router /user/:id, parameters separated by spaces [name] [type] [required] [comment],	@param id int true "user_id"
query	The query parameter of route, /user?id=, parameters same as @param	@query id int true "user_id"
header	The request HTTP header parameter, parameters same as @param	@header X-Request-ID string false "request id"
form	The form parameter of request, parameters same as @param	@form id int true "user_id"
deprecated	Mark api as deprecated.	@deprecated

Response

1. response user defined struct.

   type User struct {
       ID int `json:"id"`
       Name string `json:"name"`
   }
   
   //@response 200 User "description"

2. response struct with array.

   //@response 200 []User

3. a composition common response.

   type Response struct {
       Code int `json:"code"`
       Msg string `json:"msg"`
       Data interface{} `json:"data"`
   }
   
   //@response 200 Response{code=10001,msg="some error"} "some error description"
   //@response 200 Response{code=0,data=User} "success description"
   //@response 200 Response{code=0,data=[]User} "success description"

   if import package of common.Response:

   import (
       "common"
   )
   
   //@response 200 common.Response{code=0,data=User} "success description"

4. example value of struct

   type User struct {
       ID int `json:"id" example:"100010"`
       Name string `json:"name" example:"user name"`
   } //User Infomation

Mock

1. generate apis mocks files. add //mock at the end of response, default use first.

   //@response 200 Response{code=0,data=[]User} "success description" //mock

   generate apis mocks files, default generated in the directory ./docs/mocks.

   apidocgen --dir=common,svc-user --gen-mocks

2. serve the mock server from generated mock files.

   apidocgen mock --data=./mocks --listen=:8001

3. serve the mock server from source code (dot't generate mock files).

   apidocgen --dir=common,svc-user --mock --mock-listen=:8001

4. request mock server using curl client.

   $ curl -X POST -d "" localhost:8001/user/account/login   
   {
     "code": 0,
     "data": {
       "welcome_msg": "string"
     },
     "msg": "success"
   }