gateway/api-doc
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

优化文档数据结构体 #19

Merged
zhangdeman merged 2 commits from feature/parse_openapi into master 2025-02-27 20:45:36 +08:00
Conversation 0 Commits 2 Files Changed 4 +28 -29
4 changed files with 28 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
define/openapi.go
View File

@ -132,7 +132,7 @@ type Schema struct {
Required []string `json:"required,omitempty"` // 必传属性列表
Enum []any `json:"enum,omitempty"` // 枚举值列表
XEnumDescription map[string]string `json:"x-enumDescriptions,omitempty"` // 枚举值描述的扩展, redoc-free支持
Type string `json:"type,omitempty"` // 类型
Type any `json:"type,omitempty"` // 类型 (string | []string)
Items *PropertyXOf `json:"items,omitempty"` // items 必须存在如果 type 的值是 array。
OneOf []*PropertyXOf `json:"oneOf,omitempty"` // type 是一个对象, allOf 指向对象描述
Ref string `json:"$ref,omitempty"` // 类型引用
@ -150,7 +150,7 @@ type Schema struct {
//
// Date : 17:05 2024/7/19
type Property struct {
Type string `json:"type,omitempty"` // 数据类型, swagger本身的定义
Type any `json:"type,omitempty"` // 数据类型(string | []string), swagger本身的定义
Format string `json:"format,omitempty"` // 对应编程语言中的数据类型描述
Enum []any `json:"enum,omitempty"` // 枚举值列表
XEnumDescription map[string]string `json:"x-enumDescriptions,omitempty"` // 枚举值描述的扩展, redoc-free支持
@ -165,7 +165,7 @@ type Property struct {
OneOf []*PropertyXOf `json:"oneOf,omitempty"` // type 是一个对象, allOf 指向对象描述
AnyOf []*PropertyXOf `json:"anyOf,omitempty"` // type 是一个对象, allOf 指向对象描述
Items *PropertyXOf `json:"items,omitempty"` // items 必须存在如果 type 的值是 array。
AdditionalProperties *PropertyXOf `json:"additionalProperties,omitempty"` // additionalProperties 是一个用于描述模型中包含未在属性列表中定义的额外属性的选项。它允许接受任意的一个或多个键值对。它的作用是为了在模型定义中包含未知或动态属性。通常，在设计 API 时，我们无法预先知道 API 用户会传递什么样的额外属性，这时就可以使用 additionalProperties 功能来灵活地处理这些未知属性。
AdditionalProperties any `json:"additionalProperties,omitempty"` // additionalProperties(PropertyXOf | bool) 是一个用于描述模型中包含未在属性列表中定义的额外属性的选项。它允许接受任意的一个或多个键值对。它的作用是为了在模型定义中包含未知或动态属性。通常，在设计 API 时，我们无法预先知道 API 用户会传递什么样的额外属性，这时就可以使用 additionalProperties 功能来灵活地处理这些未知属性。
Properties map[string]*Property `json:"properties,omitempty"` // type = object 时, 定义对象属性
Ref string `json:"$ref,omitempty"` // 对描述的引用
}
@ -227,7 +227,7 @@ type RequestBody struct {
// Date : 17:21 2024/7/19
type Media struct {
Schema *Schema `json:"schema,omitempty"` // 定义此媒体类型的结构。
Example string `json:"example,omitempty"` // 媒体类型的示例。示例对象应该符合此媒体类型的格式， 这里指定的example对象 object is mutually exclusive of the examples object. 而且如果引用的schema也包含示例，在这里指定的example值将会覆盖schema提供的示例。
Example map[string]any `json:"example,omitempty"` // 媒体类型的示例。示例对象应该符合此媒体类型的格式， 这里指定的example对象 object is mutually exclusive of the examples object. 而且如果引用的schema也包含示例，在这里指定的example值将会覆盖schema提供的示例。
Examples map[string]*Example `json:"examples,omitempty"` // 媒体类型的示例，每个媒体对象的值都应该匹配它对应的媒体类型的格式。 The examples object is mutually exclusive of the example object. 而且如果引用的schema也包含示例，在这里指定的example值将会覆盖schema提供的示例。
Encoding map[string]*Encoding `json:"encoding,omitempty"` // 属性名与编码信息的映射。每个属性名必须存在于schema属性的key中，当媒体类型等于multipart或application/x-www-form-urlencoded时，编码对象信息仅适用于requestBody。
}

4
generate.go
View File

@ -207,7 +207,7 @@ func (g *Generate) AddApiFromInAndOut(uriPrefix string, paramType reflect.Type,
Schema: &define.Schema{
Ref: g.getSchemaRef(paramSchemaName),
},
Example: "",
Example: nil,
Examples: nil,
Encoding: nil,
}
@ -220,7 +220,7 @@ func (g *Generate) AddApiFromInAndOut(uriPrefix string, paramType reflect.Type,
Schema: &define.Schema{
Ref: g.getSchemaRef(resultSchemaName),
},
Example: "",
Example: nil,
Examples: nil,
Encoding: nil,
}

37
parser.go
View File

@ -8,34 +8,35 @@
package api_doc
import (
"errors"
"git.zhangdeman.cn/gateway/api-doc/define"
"git.zhangdeman.cn/zhangdeman/serialize"
"github.com/tidwall/gjson"
"strings"
)
// Parse 解析swagger文档
// ParseOpenapi3 解析openapi文档
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:54 2024/12/23
func Parse(docUrl string) (*define.DocParseResult, error) {
// Date : 21:02 2025/2/25
func ParseOpenapi3(docUrl string, docContent string) (*define.OpenapiDoc, error) {
var (
err error
docContent []byte
docRes define.OpenapiDoc
err error
docByte []byte
)
if docContent, err = serialize.File.ReadFromRemote(docUrl); nil != err {
if len(docContent) < 2 {
if len(docUrl) == 0 {
return nil, errors.New("doc url and doc content all empty")
}
if docByte, err = serialize.File.ReadFromRemote(docUrl); nil != err {
return nil, err
}
} else {
docByte = []byte(docContent)
}
if err = serialize.JSON.UnmarshalWithNumber(docByte, &docRes); nil != err {
return nil, err
}
swaggerVersion := gjson.GetBytes(docContent, "swagger").String()
if "" == swaggerVersion || !strings.HasPrefix(swaggerVersion, "2.") {
// 未指定swagger版本或swagger版本3.x
return ParseOpenapi3(docContent)
}
return ParseSwagger2(docContent)
}
func ParseOpenapi3(docContent []byte) (*define.DocParseResult, error) {
return nil, nil
return &docRes, nil
}

8
parser_test.go
View File

@ -11,7 +11,6 @@ import (
"encoding/json"
"fmt"
"git.zhangdeman.cn/gateway/api-doc/define"
"git.zhangdeman.cn/zhangdeman/serialize"
"reflect"
"testing"
)
@ -96,8 +95,7 @@ func Test_parser_Openapi3(t *testing.T) {
fmt.Println(string(byteData))
}
func TestParseForSwagger(t *testing.T) {
docUrl := "https://git.zhangdeman.cn/swagger.v1.json"
res, _ := Parse(docUrl)
serialize.JSON.ConsoleOutput(res)
func Test_parse_Openapi3_doc(t *testing.T) {
res, err := ParseOpenapi3("http://localhost:10990/static-server/github-openapi.json", "")
fmt.Println(res, err)
}