// Package openapi ... // // Description : openapi ... // // Author : go_developer@163.com<白茶清欢> // // Date : 2026-01-05 17:20 package openapi import ( "reflect" "git.zhangdeman.cn/zhangdeman/consts" "github.com/getkin/kin-openapi/openapi3" ) // NewGenerate 生成文档实例 func NewGenerate() *Generate { return &Generate{ doc: &openapi3.T{ Extensions: map[string]any{}, OpenAPI: "3.1.0", Components: &openapi3.Components{ Extensions: map[string]any{}, Origin: &openapi3.Origin{ Key: &openapi3.Location{ Line: 0, Column: 0, }, Fields: make(map[string]openapi3.Location), }, Schemas: map[string]*openapi3.SchemaRef{}, Parameters: map[string]*openapi3.ParameterRef{}, Headers: map[string]*openapi3.HeaderRef{}, RequestBodies: map[string]*openapi3.RequestBodyRef{}, Responses: map[string]*openapi3.ResponseRef{}, SecuritySchemes: map[string]*openapi3.SecuritySchemeRef{}, Examples: map[string]*openapi3.ExampleRef{}, Links: map[string]*openapi3.LinkRef{}, Callbacks: map[string]*openapi3.CallbackRef{}, }, Info: &openapi3.Info{ Extensions: map[string]any{}, Origin: &openapi3.Origin{ Key: &openapi3.Location{ Line: 0, Column: 0, }, Fields: make(map[string]openapi3.Location), }, Title: "服务 API接口 文档", Description: "服务 API接口 文档", TermsOfService: "", Contact: &openapi3.Contact{ Extensions: map[string]any{}, Origin: &openapi3.Origin{ Key: &openapi3.Location{ Line: 0, Column: 0, }, Fields: make(map[string]openapi3.Location), }, Name: "developer", URL: "", Email: "developer@test.com", }, License: &openapi3.License{ Extensions: map[string]any{}, Origin: &openapi3.Origin{ Key: &openapi3.Location{ Line: 0, Column: 0, }, Fields: make(map[string]openapi3.Location), }, Name: consts.LicenseApache20, URL: consts.LicenseUrlTable[consts.LicenseApache20], }, Version: "0.0.1", }, Paths: &openapi3.Paths{ Extensions: map[string]any{}, Origin: &openapi3.Origin{ Key: &openapi3.Location{ Line: 0, Column: 0, }, Fields: make(map[string]openapi3.Location), }, }, Security: []openapi3.SecurityRequirement{}, Servers: []*openapi3.Server{}, Tags: []*openapi3.Tag{}, ExternalDocs: &openapi3.ExternalDocs{ Extensions: map[string]any{}, Origin: nil, Description: "", URL: "", }, }, } } // Generate 生成 OpenApi 标准规范的文档 type Generate struct { doc *openapi3.T } // AddApiDoc 添加接口文档 func (g *Generate) AddApiDoc(request any, response any) error { var ( err error requestType reflect.Type responseType reflect.Type ok bool ) // 初始化请求数据与响应数据类型 if requestType, ok = request.(reflect.Type); !ok { requestType = reflect.TypeOf(request) if requestType.Kind() == reflect.Ptr { requestType = requestType.Elem() } } if responseType, ok = response.(reflect.Type); !ok { responseType = reflect.TypeOf(response) if responseType.Kind() == reflect.Ptr { responseType = responseType.Elem() } } requestTypeStr := requestType.String() if _, exist := g.doc.Components.Schemas[requestTypeStr]; !exist { g.doc.Components.Schemas[requestTypeStr] = GenerateOpenAPISchema(requestType) } responseTypeStr := requestType.String() if _, exist := g.doc.Components.Schemas[responseTypeStr]; !exist { g.doc.Components.Schemas[responseTypeStr] = GenerateOpenAPISchema(responseType) } return err }