goas

Based on yvasiyarov/swagger repository.

Generate OpenAPI Specification json file with comments in Go.

Limit

Currently, only JSON supported

Install

go get -u github.com/mikunalpha/goas/cmd/goas

Usage

Comments in main.go

// @Version 1.0.0
// @Title Backend API
// @Description API usually works as expected. But sometimes its not true.
// @ContactName Abcd
// @ContactEmail [email protected]
// @ContactURL http://someurl.oxox
// @TermsOfServiceUrl http://someurl.oxox
// @LicenseName MIT
// @LicenseURL https://en.wikipedia.org/wiki/MIT_License
// @Server http://www.fake.com Server-1
// @Server http://www.fake2.com Server-2

Comments for API handleFunc

type User struct {
  Id   uint64 `json:"id" example:"100"`
  Name string `json:"name" example:"Mikun"` 
}

type UsersResponse struct {
  Data []Users `json:"users" example:"[{\"id\":100, \"name\":\"Mikun\"}]"`
}

type Error struct {
  Code string `json:"code"`
  Msg  string `json:"msg"`
}

type ErrorResponse struct {
  ErrorInfo Error `json:"error"`
}

// @Title Get user list of a group.
// @Description Get users related to a specific group.
// @Param  group_id  path  int  true  "Id of a specific group."
// @Success  200  {object}  UsersResponse  "UsersResponse JSON"
// @Failure  400  {object}  ErrorResponse  "ErrorResponse JSON"
// @Resource users
// @Router /api/group/{group_id}/users [get]
func GetGroupUsers() {
  // ...
}

// @Title Get user list of a group.
// @Description Create a new user.
// @Param  user  body  User  true  "Info of a user."
// @Success  200  {object}  User           "UsersResponse JSON"
// @Failure  400  {object}  ErrorResponse  "ErrorResponse JSON"
// @Resource users
// @Router /api/user [post]
func PostUser() {
  // ...
}

Go to the folder where is main.go in

goas --package github.com/mikunalpha/goas/example --output oas.json