aoi-hosizora / goapidoc

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

Introduction

• 👋 Hi! Here is AoiHosizora (青いほしぞら), majors in Intelligent Software and Robotics, Software Engineering.
• 📝 Speaking languages: Mandarin Chinese (Native), Teo-Swa-uê (Native), English (CET-6), Japanese (JLPT-N1).
• 🏢 Some owned GitHub organizations: ah-shellext & ah-forklib, my public email: [email protected].
• 🚀 Interest areas: distributed backend system development, desktop client and android client development.
• ⚡ Favorite programming languages: Go, Dart, C#, Kotlin, Rust, Typescript, etc.

Coding status

goapidoc's Issues

[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.

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>>",
	})

[PLAN] Add api blueprint support

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

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"
  }
},

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")
	}

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)
}

Apib order is not stable

Need to check map in generate_apib.go

Some features of field

Add some features of field: example min max regex