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  }