openapi

Author: metaleap

srv/codegen_apistuff.go

@@ -209,9 +209,28 @@ func codegenOpenApi(apiRefl *apiReflect) (didFsWrites []string) {
 	out_file_path := curMainStaticDirPath_App + "/openapi.json"
 
 	openapi := yopenapi.OpenApi{
-		Info:    yopenapi.Info{Title: Cfg.YO_APP_DOMAIN, Version: time.Now().Format("06.__2")},
 		OpenApi: yopenapi.Version,
 		Paths:   map[string]yopenapi.Path{},
+		Info: yopenapi.Info{Title: Cfg.YO_APP_DOMAIN, Version: time.Now().Format("06.__2"), Descr: str.Replace(`
+Request/response rules and how to read their example renditions:
+- All request headers, URL query-string parameters and response headers are identical over the whole set of all operations. Only request and response bodies are operation-specific.
+- Request bodies **must never** be empty or the JSON ´null´: the empty request body is the JSON ´{}´.
+- Response bodies will never be empty, but may be the JSON ´null´.
+- All request fields are by default optional and ommittable / ´null´able, **any exceptions** to this are indicated by the operation's listed known-error responses.
+- Example values rendered in this doc:
+  - ´true´ indicates any ´boolean´ value, regardless of the actual real value in a call
+  - ´"someStr"´ indicates any ´string´ value
+  - date-time values are indicated by RFC3339-formatted ´string´ examples
+  - signed-integer ´number´s are indicated by a negative-number example indicating the minimum (type-wise, not operation-specific) permissible value, with the maximum being the corresponding positive-number counterpart
+  - unsigned-integer ´number´s are indicated by a positive-number example indicating the maximum (type-wise, not not operation-specific) permissible value, with the minimum being ´0´
+  - floating-point ´number´s are indicated by a positive-number example indicating the maximum (type-wise, not not operation-specific) permissible value, with the minimum being the corresponding negative-number counterpart
+
+More about error responses:
+- All are ´text/plain´.
+- In addition to those listed in this doc (thrown by the service under the indicated conditions), other error responses are always entirely possible and not exhaustively documentable feasibly (such as DB, file-system or network disruptions). Those caught by the service will be ´500´s, others (ie. from load-balancers / gateways / reverse-proxies etc. in front of the service) might have any HTTP status code.
+- The well-known error responses listed here have been recursively determined by code-path walking. Among them are some that logically could not possibly ever occur for that operation, yet identifying those (to filter them out of the listing) is (so far) out of scope for our ´openapi.json´ generation.
+- The well-known (thrown rather than caught) errors have their code-identifier-compatible (spaceless ASCII) enumerant-name as their entire text response, others preserve simply their original (usually human-language) error message fully. Hence, error responses are inherently ´switch/case´able.
+		`, str.Dict{"´": "`"})},
 	}
 	openapi.Info.Contact.Name, openapi.Info.Contact.Url = "Permalink", "https://"+Cfg.YO_APP_DOMAIN+"/"+StaticFilesDirName_App+"/"+filepath.Base(out_file_path)
 
@@ -244,9 +263,10 @@ func codegenOpenApi(apiRefl *apiReflect) (didFsWrites []string) {
 			},
 		}}
 		for http_status_code, errs := range sl.Grouped(api_method.KnownErrs(), func(it Err) string { return str.FromInt(it.HttpStatusCodeOr(500)) }) {
+			str_errs := sl.As(errs, Err.String)
 			path.Post.Responses[http_status_code] = yopenapi.Resp{
-				Descr:   "foo",
-				Content: map[string]yopenapi.Media{"text/plain": {Examples: kv.FromKeys(errs, func(it Err) yopenapi.Example { return yopenapi.Example{Value: it} })}},
+				Descr:   "Possible `text/plain` responses:\n- `" + str.Join(str_errs, "`\n- `") + "`",
+				Content: map[string]yopenapi.Media{"text/plain": {Examples: kv.FromKeys(str_errs, func(it string) yopenapi.Example { return yopenapi.Example{Value: it} })}},
 			}
 		}
 		openapi.Paths["/"+method.Path] = path

srv/openapi/openapi.go

@@ -7,7 +7,9 @@ import (
 	"reflect"
 	"time"
 
+	. "yo/cfg"
 	. "yo/util"
+	"yo/util/str"
 )
 
 // yoValiOnly yoFail
@@ -22,6 +24,8 @@ type OpenApi struct {
 
 type Info struct {
 	Title   string `json:"title"`
+	Summary string `json:"summary,omitempty"`
+	Descr   string `json:"description,omitempty"`
 	Version string `json:"version"`
 	Contact struct {
 		Name string `json:"name"`
@@ -84,15 +88,16 @@ type Example struct {
 
 var tyTime = reflect.TypeOf(time.Time{})
 
-func dummyOf(ty reflect.Type, level int, typesDone map[reflect.Type]bool) reflect.Value {
+// TODO: type-recursion-safety
+func dummyOf(ty reflect.Type, level int) reflect.Value {
 	dummy_ptr := func(dummy reflect.Value) reflect.Value {
 		alloc := reflect.New(dummy.Type())
 		alloc.Elem().Set(dummy)
 		return alloc
 	}
 
 	if ty.Kind() == reflect.Pointer {
-		return dummyOf(ty.Elem(), level, typesDone)
+		return dummyOf(ty.Elem(), level)
 	}
 	if ty.ConvertibleTo(tyTime) || tyTime.ConvertibleTo(ty) || ty.AssignableTo(tyTime) || tyTime.AssignableTo(ty) {
 		return reflect.ValueOf(time.Now()).Convert(ty)
@@ -131,26 +136,31 @@ func dummyOf(ty reflect.Type, level int, typesDone map[reflect.Type]bool) reflec
 	case reflect.Slice:
 		dummy = reflect.MakeSlice(ty, 0, 1)
 		ty_item := ty.Elem()
-		append_item := dummyOf(ty_item, level+1, typesDone)
+		append_item := dummyOf(ty_item, level+1)
 		if ty_item.Kind() == reflect.Pointer {
 			append_item = dummy_ptr(append_item)
 		}
 		dummy = reflect.Append(dummy, append_item)
 	case reflect.Map:
 		dummy = reflect.MakeMap(ty)
 		ty_item := ty.Elem()
-		append_item := dummyOf(ty_item, level+1, typesDone)
+		append_item := dummyOf(ty_item, level+1)
 		if ty_item.Kind() == reflect.Pointer {
 			append_item = dummy_ptr(append_item)
 		}
-		dummy.SetMapIndex(reflect.ValueOf("someKey"), append_item)
+		dummy.SetMapIndex(reflect.ValueOf("someMapKey1"), append_item)
+		dummy.SetMapIndex(reflect.ValueOf("some_map_key_2"), append_item)
 	case reflect.Struct:
 		for i := 0; i < ty.NumField(); i++ {
 			field := ty.Field(i)
 			if !field.IsExported() {
 				continue
 			}
-			field_dummy := dummyOf(field.Type, level+1, typesDone)
+			if str.Has(str.Lo(field.Name), "password") {
+				dummy.Field(i).Set(reflect.ValueOf("lenOfMin" + str.FromInt(Cfg.YO_AUTH_PWD_MIN_LEN) + "AndMax" + str.FromInt(Cfg.YO_AUTH_PWD_MAX_LEN)))
+				continue
+			}
+			field_dummy := dummyOf(field.Type, level+1)
 			if field.Type.Kind() == reflect.Pointer && field_dummy.Kind() != reflect.Pointer {
 				field_dummy = dummy_ptr(field_dummy)
 			}
@@ -159,10 +169,9 @@ func dummyOf(ty reflect.Type, level int, typesDone map[reflect.Type]bool) reflec
 			}
 		}
 	}
-
 	return dummy
 }
 
 func DummyOf(ty reflect.Type) any {
-	return dummyOf(ty, 0, map[reflect.Type]bool{}).Interface()
+	return dummyOf(ty, 0).Interface()
 }

util/err.go

@@ -6,6 +6,7 @@ type Err string
 
 var errSubstrToHttpStatusCode = map[string]int{
 	"DoesNotExist":  400, // no 404 wanted for those, there's NotFound below for that
+	"ContentLength": 400,
 	"WrongPassword": 401,
 	"MustBeAdmin":   401,
 	"Unauthorized":  403,

util/kv/kv.go

@@ -18,16 +18,16 @@ func Fill[K comparable, V any](dst map[K]V, from map[K]V) map[K]V {
 	return dst
 }
 
-func FromKeys[K comparable, V any](keys []K, value func(K) V) map[K]V {
-	ret := make(map[K]V, len(keys))
+func FromKeys[TKey comparable, TVal any](keys []TKey, value func(TKey) TVal) map[TKey]TVal {
+	ret := make(map[TKey]TVal, len(keys))
 	for _, key := range keys {
 		ret[key] = value(key)
 	}
 	return ret
 }
 
-func FromValues[K comparable, V any](values []V, key func(V) K) map[K]V {
-	ret := make(map[K]V, len(values))
+func FromValues[TKey comparable, TVal any](values []TVal, key func(TVal) TKey) map[TKey]TVal {
+	ret := make(map[TKey]TVal, len(values))
 	for _, val := range values {
 		ret[key(val)] = val
 	}