trpc.group/trpc-go/trpc-cmdline@v1.0.9/util/apidocs/swagger.go (about) 1 // Tencent is pleased to support the open source community by making tRPC available. 2 // 3 // Copyright (C) 2023 THL A29 Limited, a Tencent company. 4 // All rights reserved. 5 // 6 // If you have downloaded a copy of the tRPC source code from Tencent, 7 // please note that tRPC source code is licensed under the Apache 2.0 License, 8 // A copy of the Apache 2.0 License is included in this file. 9 10 package apidocs 11 12 import ( 13 "fmt" 14 15 "trpc.group/trpc-go/trpc-cmdline/descriptor" 16 "trpc.group/trpc-go/trpc-cmdline/params" 17 ) 18 19 // SwaggerJSON defines the structure of the JSON that contains the swagger API documentation. 20 type SwaggerJSON struct { 21 Swagger string `json:"swagger"` // Version of Swagger. 22 Info InfoStruct `json:"info"` // Description information of the API document. 23 24 Consumes []string `json:"consumes"` 25 Produces []string `json:"produces"` 26 27 // A collection of detailed information for the request method. 28 Paths Paths `json:"paths"` 29 // Various model definitions, including the structure definitions of method input and output parameters. 30 Definitions map[string]ModelStruct `json:"definitions"` 31 } 32 33 // NewSwagger generates swagger documents. 34 func NewSwagger(fd *descriptor.FileDescriptor, option *params.Option) (*SwaggerJSON, error) { 35 refPrefix = "#/definitions/" 36 if fd.FD == nil { 37 return nil, fmt.Errorf("nil fd") 38 } 39 40 // Get the data model obtained from the pb file. 41 defs := NewDefinitions(option, append(allDependenciesFds(fd.FD), fd.FD)...) 42 43 // Assemble the information of each method. 44 paths, err := NewPaths(fd, option, defs) 45 if err != nil { 46 return nil, fmt.Errorf("generate swagger error: %w", err) 47 } 48 49 // Get file information to assemble Swagger JSON document header information. 50 infoMap, err := NewInfo(fd) 51 if err != nil { 52 return nil, err 53 } 54 55 // AssembleSwaggerJSON assembles the complete Swagger JSON document. 56 swaggerJSON := &SwaggerJSON{ 57 Swagger: "2.0", 58 Info: infoMap, 59 Consumes: []string{"application/json"}, 60 Produces: []string{"application/json"}, 61 Paths: paths, 62 Definitions: defs.getUsedModels(paths), 63 } 64 return swaggerJSON, nil 65 } 66 67 func allDependenciesFds(d descriptor.Desc) []descriptor.Desc { 68 deps := d.GetDependencies() 69 if len(deps) == 0 { 70 return nil 71 } 72 73 var allDeps []descriptor.Desc 74 allDeps = append(allDeps, deps...) 75 for _, dep := range deps { 76 allDeps = append(allDeps, allDependenciesFds(dep)...) 77 } 78 return allDeps 79 }