Repository files navigation

English |简体中文

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

go install github.com/alovn/apidocgen@latest

$ apidocgen --helpapidocgen is a toolfor Go to generate apis markdown docs and mocks. For example:apidocgen --dir= --excludes= --output= --output-index= --template= --single --gen-mocksapidocgen --mock --mock-listen=:8001apidocgen mock --data= --listen=Usage:  apidocgen [flags]  apidocgen [command]Available Commands:help        Help about anycommand  mock          version     print versionFlags:      --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, --helphelpfor 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 apidocsUse"apidocgen [command] --help"for more information about a command.

The built-in templates includemarkdown andapidocs, default ismarkdown.

The templateapidocs is the template for generate websiteapidocs.

You can also use the custom template:

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

apidocgen supported any web frameworks. here are an example usingbytego.

1. Add API annotations in main.go code:

   //@title UserService//@service svc-user//@version 1.0.1//@desc the api about users//@baseurl /userfuncmain() {r:=bytego.New()c:=controller.NewController()//@group account//@title Account//@desc account register and loginaccount:=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 alovnfunc (c*Controller)Login(c*bytego.Ctx) {//bind LoginRequestres:=common.NewResponse(0,"success",&LoginResponse{WelcomeMsg:"welcome",    })c.JSON(http.StatusOK,res)}

3. Executeapidocgen.

   apidocgen

   The markdown files will be generated in./docs.

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

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

1. response user defined struct.

   typeUserstruct {IDint`json:"id"`Namestring`json:"name"`}//@response 200 User "description"

2. response struct with array.

   //@response 200 []User

3. a composition common response.

   typeResponsestruct {Codeint`json:"code"`Msgstring`json:"msg"`Datainterface{}`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 ofcommon.Response:

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

4. example value of struct

   typeUserstruct {IDint`json:"id" example:"100010"`Namestring`json:"name" example:"user name"`}//User Infomation

1. generate apis mocks files. add//mock at the end ofresponse, 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 usingcurl client.

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