aoi-hosizora / goapidoc

A golang library for generating api document, including swagger2 and apib.

goapidoc

• A golang library for generating api document, including swagger2 and apib.

Function

• Support api, routes and definitions information
• Support generic definition type
• Support most of the functions for swagger 2
• Support basic functions for API Blueprint 1A

Usage

• Visit generate_test.go for detail examples, and api1.json / api2.apib for generated documents.

package main

import (
	. "github.com/Aoi-hosizora/goapidoc"
)

func main() {
	SetDocument("localhost:60001", "/",
		NewInfo("Demo api", "This is a demo api only for testing goapidoc.", "1.0.0").
			License(NewLicense("MIT", "")).
			Contact(NewContact("", "https://github.com/Aoi-hosizora", "")),
	)

	SetOption(NewOption().
		Schemes("http").
		Tags(
			NewTag("Authorization", "auth-controller"),
			NewTag("User", "user-controller"),
		).
		Securities(
			NewApiKeySecurity("jwt", HEADER, "Authorization"),
		).
		GlobalParams(
			NewQueryParam("force_refresh", "boolean", false, "force refresh flag").Default(false),
			NewHeaderParam("X-Special-Flag", "string", false, "a special flag in header").Example("token-xxx"),
		),
	)

	AddOperations(
		NewPostOperation("/auth/register", "Sign up").
			Tags("Authorization").
			Params(
				NewBodyParam("param", "RegisterParam", true, "register param"),
			).
			Responses(
				NewResponse(200, "Result"),
			),

		NewPostOperation("/auth/login", "Sign in").
			Tags("Authorization").
			Params(
				NewBodyParam("param", "LoginParam", true, "login param"),
			).
			Responses(
				NewResponse(200, "_Result<LoginDto>"),
			),

		NewGetOperation("/auth/me", "Get the authorized user").
			Tags("Authorization").
			Securities("jwt").
			Responses(
				NewResponse(200, "_Result<UserDto>"),
			),

		NewDeleteOperation("/auth/logout", "Sign out").
			Tags("Authorization").
			Securities("jwt").
			Responses(
				NewResponse(200, "Result"),
			),
	)

	AddOperations(
		NewGetOperation("/user", "Query all users").
			Tags("User").
			Securities("jwt").
			Params(
				NewQueryParam("page", "integer#int32", false, "query page").Default(1),
				NewQueryParam("limit", "integer#int32", false, "page size").Default(20),
				NewQueryParam("force_refresh", "boolean", false, "force refresh flag for querying users").Default(false),
				NewHeaderParam("X-Special-Flag", "string", true, "a special flag in header, which must be set for querying users"),
			).
			Responses(
				NewResponse(200, "_Result<_Page<UserDto>>"),
			),

		NewGetOperation("/user/{id}", "Query the specific user").
			Tags("User").
			Securities("jwt").
			Params(
				NewPathParam("id", "integer#int64", true, "user id"),
			).
			Responses(
				NewResponse(200, "_Result<UserDto>"),
			),

		NewPutOperation("/user", "Update the authorized user").
			Tags("User").
			Securities("jwt").
			Params(
				NewBodyParam("param", "UpdateUserParam", true, "update user param"),
			).
			Responses(
				NewResponse(200, "Result"),
			),

		NewDeleteOperation("/user", "Delete the authorized user").
			Tags("User").
			Securities("jwt").
			Responses(
				NewResponse(200, "Result"),
			),
	)

	AddDefinitions(
		NewDefinition("Result", "Global response").
			Properties(
				NewProperty("code", "integer#int32", true, "status code"),
				NewProperty("message", "string", true, "status message"),
			),

		NewDefinition("_Result", "Global generic response").
			Generics("T").
			Properties(
				NewProperty("code", "integer#int32", true, "status code"),
				NewProperty("message", "string", true, "status message"),
				NewProperty("data", "T", true, "response data"),
			),

		NewDefinition("_Page", "Global generic page response").
			Generics("T").
			Properties(
				NewProperty("page", "integer#int32", true, "current page"),
				NewProperty("limit", "integer#int32", true, "page size"),
				NewProperty("total", "integer#int32", true, "total count"),
				NewProperty("data", "T[]", true, "response data"),
			),

		NewDefinition("LoginParam", "Login parameter").
			Properties(
				NewProperty("username", "string", true, "username"),
				NewProperty("password", "string", true, "password"),
			),

		NewDefinition("RegisterParam", "Register parameter").
			Properties(
				NewProperty("username", "string", true, "username"),
				NewProperty("password", "string", true, "password"),
			),

		NewDefinition("UpdateUserParam", "Update user parameter").
			Properties(
				NewProperty("username", "string", true, "username"),
				NewProperty("bio", "string", true, "user bio"),
				NewProperty("gender", "string", true, "user gender").Enum("Secret", "Male", "Female"),
				NewProperty("birthday", "string#date", true, "user birthday"),
			),

		NewDefinition("LoginDto", "Login response").
			Properties(
				NewProperty("user", "UserDto", true, "authorized user"),
				NewProperty("token", "string", true, "access token"),
			),

		NewDefinition("UserDto", "User response").
			Properties(
				NewProperty("id", "integer#int64", true, "user id"),
				NewProperty("username", "string", true, "username"),
				NewProperty("bio", "string", true, "user bio"),
				NewProperty("gender", "string", true, "user gender").Enum("Secret", "Male", "Female"),
				NewProperty("birthday", "string#date", true, "user birthday"),
			),
	)

	_, _ = SaveSwaggerYaml("./docs/api3.yaml")
	_, _ = SaveSwaggerJson("./docs/api3.json")
	_, _ = SaveApib("./docs/api3.apib")
}

References

• OpenAPI Specification 2.0
• API Blueprint Specification

goapidoc's Issues

Some features of field

Add some features of field: example min max regex

Add Get methods and add more Set methods

Sometimes I need to update some properties for existed value.
So it is necessity to use Get methods and use more Set methods to update those.

func RuntimeUpdateSwaggerSpec() {
	// config.Configs().Meta.Port
	host := goapidoc.GetDocument().GetHost()
	goapidoc.GetDocument().Host(host)
}

Complete the generate test

Complete the TestGenerate, not just use the if err != nil {}.

goapidoc/generate_test.go

Lines 383 to 399 in db16945

	_, err := GenerateSwaggerYaml("./docs/api.yaml")
	if err != nil {
	log.Println(err)
	t.Fatal("yaml")
	}
	_, err = GenerateSwaggerJson("./docs/api.json")
	if err != nil {
	log.Println(err)
	t.Fatal("json")
	}
	_, err = GenerateApib("./docs/api.apib")
	if err != nil {
	log.Println(err)
	t.Fatal("apib")
	}

[PLAN] Add api blueprint support

Add a method to Generate apib file: https://apiblueprint.org/.

Add more test for apitype.go

Fix some potential bugs in apitype.go and rewrite test with test cases.

Some ugly tests now:

goapidoc/generate_test.go

Lines 105 to 114 in cf47f71

	def := &Definition{
	generics: []string{"T", "U", "V"},
	properties: []*Property{
	{typ: "inT[]"},
	{typ: "O<inT[], T[], T, inT<int>>"},
	{typ: "T"},
	{typ: "tT<T<tT>[][], T>[]"},
	{typ: "TtT<T,tT[],T[][]>[]"},
	},
	}

goapidoc/generate_test.go

Lines 162 to 167 in cf47f71

	newDefs := prehandleGenericList(defs, []string{
	"Result<Page<User>>",
	"Result3<User, Page<Result2<Login, Page<Login>>>, String[]>",
	"Integer",
	"Result2<String, Result2<String, String>>",
	})

[BUG] bug with has multiple tags in path

Demo code:

goapidoc.NewPath("GET", "/v1/policy", "查询所有策略").
	WithTags("Policy").
	// WithTags("Administration").
	WithSecurities("Jwt").
	WithResponses(goapidoc.NewResponse(200).WithType("_Result<_Page<PolicyDto>>")),

The first tags (policy) will be ignore and only the last tag will be shown in spec.json.

Apib order is not stable

Need to check map in generate_apib.go

Body request parameter should be in schema but not parameter

"parameters": [
  {
    "name": "param",
    "in": "body",
    "required": true,
    "type": "array",
    "description": "query string, format: [cid:id]",
    "items": {
      "type": "string"
    }
  }
],

Failed to parse unresolved generic parameter in swagger-ui

Errors
Hide
Resolver error at definitions._Page.properties.data.items.$ref
Could not resolve reference because of: Could not resolve pointer: /definitions/T does not exist in document
Resolver error at definitions._Result.properties.data.$ref
Could not resolve reference because of: Could not resolve pointer: /definitions/T does not exist in document

"data": {
  "type": "array",
  "required": true,
  "description": "page data",
  "items": {
    "originRef": "T",
    "$ref": "#/definitions/T"
  }
},