feat: add tag groups extension

Josh Newman · Josh Newman · commit cf3273d0be3d · 2022-12-27T18:18:19.000-07:00
diff --git a/README.md b/README.md
@@ -30,7 +30,7 @@ go install github.com/technicallyjosh/protoc-gen-openapi@latest
 | `version`          | The version of the API.                                                           | 0.0.1            |
 | `title`            | The title of the API.                                                             |                  |
 | `description`      | A description of the API.                                                         |                  |
-| `ignore`           | A list of package names to ignore delimited with a pipe.                          |                  |
+| `ignore`           | A list of proto package names to ignore delimited by pipes.                       |                  |
 | `default_response` | The default response to be used.<sup>1</sup>                                      |                  |
 | `content_type`     | The content type to be associated with all operations.<sup>1</sup>                | application/json |
 | `json_names`       | Use the JSON names that Protobuf provides. Otherwise, proto field names are used. | false            |
@@ -149,6 +149,7 @@ service MyService {
 ```
 
 ## Features In Progress
+
 - Path Parameters and Query
 - Field requirements (e.g. `>` `<` etc...)
 
diff --git a/api/oapi/v1/field.pb.go b/api/oapi/v1/field.pb.go
diff --git a/api/oapi/v1/field.proto b/api/oapi/v1/field.proto
@@ -14,6 +14,7 @@ extend google.protobuf.FieldOptions {
   // comments.
   string example = 5151;
 
+  // Options for a field.
   FieldOptions options = 5152;
 }
 
diff --git a/api/oapi/v1/service.pb.go b/api/oapi/v1/service.pb.go
diff --git a/api/oapi/v1/service.proto b/api/oapi/v1/service.proto
@@ -29,4 +29,8 @@ message ServiceOptions {
   // Sets the "x-displayName" extension property for the OAPI tag. This is used
   // by redocly/redoc for a friendly tag name.
   string display_name = 5;
+
+  // Adds the service to the extension x-tagGroups. If the group doesn't exist,
+  // it is created and the service tag is added to it.
+  string tag_group = 6;
 }
diff --git a/go.mod b/go.mod
@@ -4,18 +4,15 @@ go 1.19
 
 require (
 	github.com/getkin/kin-openapi v0.111.0
-	github.com/stretchr/testify v1.8.1
 	google.golang.org/protobuf v1.28.1
 	gopkg.in/yaml.v3 v3.0.1
 )
 
 require (
-	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/go-openapi/jsonpointer v0.19.5 // indirect
 	github.com/go-openapi/swag v0.19.5 // indirect
 	github.com/invopop/yaml v0.1.0 // indirect
 	github.com/mailru/easyjson v0.0.0-20190626092158-b2ccc519800e // indirect
 	github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 // indirect
-	github.com/pmezard/go-difflib v1.0.0 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 )
diff --git a/internal/generator/generator.go b/internal/generator/generator.go
@@ -87,8 +87,10 @@ func (g *Generator) Run() error {
 // buildDocument builds out the base of the OAPI document with some defaults.
 func (g *Generator) buildDocument() (*openapi3.T, error) {
 	doc := &openapi3.T{
-		ExtensionProps: openapi3.ExtensionProps{},
-		OpenAPI:        "3.0.3",
+		ExtensionProps: openapi3.ExtensionProps{
+			Extensions: make(map[string]any),
+		},
+		OpenAPI: "3.0.3",
 		Components: openapi3.Components{
 			SecuritySchemes: make(openapi3.SecuritySchemes),
 			Schemas:         make(openapi3.Schemas),
diff --git a/internal/generator/message.go b/internal/generator/message.go
@@ -13,10 +13,12 @@ var (
 
 type messageMap map[string]*protogen.Message
 
+// Set adds the specified message to the map.
 func (m messageMap) Set(val *protogen.Message) {
 	m[util.FullName(val)] = val
 }
 
+// Get returns the message by key or nil.
 func (m messageMap) Get(key string) *protogen.Message {
 	val, ok := m[key]
 	if !ok {
diff --git a/internal/generator/path.go b/internal/generator/path.go
@@ -88,6 +88,14 @@ func (g *Generator) addPathsToDoc(doc *openapi3.T, services []*protogen.Service)
 			ExtensionProps: props,
 		})
 
+		tagGroup := strings.TrimSpace(serviceOptions.TagGroup)
+		if tagGroup != "" {
+			err := addTagGroup(doc, tagGroup, tagName)
+			if err != nil {
+				return err
+			}
+		}
+
 		for _, method := range service.Methods {
 			err := g.addOperation(addOperationParams{
 				doc:            doc,
@@ -163,7 +171,7 @@ func (g *Generator) addOperation(p addOperationParams) error {
 		Tags:        []string{p.tagName},
 		Description: description,
 		OperationID: operationID,
-		Servers:     &p.doc.Servers,
+		Servers:     &openapi3.Servers{server},
 		Deprecated:  methodOptions.Deprecated,
 		Responses:   make(openapi3.Responses),
 		Summary:     methodOptions.Summary,
@@ -274,8 +282,8 @@ func (g *Generator) addOperation(p addOperationParams) error {
 		inputFullName := string(p.method.Input.Desc.FullName())
 		message := allMessages.Get(inputFullName)
 
-		// If another type is defined such as google.protobuf.Any, for now we'll just
-		// exit.
+		// If another type is defined such as google.protobuf.Any or
+		// google.protobuf.Empty, for now we'll just exit.
 		// TODO: support `Any` type for requests 🤔
 		if message != nil {
 			requestSchemaRef := &openapi3.SchemaRef{
diff --git a/internal/generator/response.go b/internal/generator/response.go
@@ -26,7 +26,7 @@ func (g *Generator) addDefaultResponse(doc *openapi3.T) error {
 			Content: openapi3.Content{
 				*g.config.ContentType: &openapi3.MediaType{
 					Schema: &openapi3.SchemaRef{
-						Ref: "#/components/schemas/" + name,
+						Ref: newSchemaRef(name),
 					},
 				},
 			},
diff --git a/internal/generator/tag_group.go b/internal/generator/tag_group.go
@@ -0,0 +1,70 @@
+package generator
+
+import (
+	"fmt"
+
+	"github.com/getkin/kin-openapi/openapi3"
+)
+
+type XTagGroups []*XTagGroup
+
+func (g *XTagGroups) find(name string) *XTagGroup {
+	for _, group := range *g {
+		if group.Name == name {
+			return group
+		}
+	}
+
+	return nil
+}
+
+// XTagGroup represents a tag group from the x-tagGroups extension.
+type XTagGroup struct {
+	Name string   `json:"name" yaml:"name"`
+	Tags []string `json:"tags" yaml:"tags"`
+}
+
+func (g *XTagGroup) tagExists(name string) bool {
+	for _, tag := range g.Tags {
+		if tag == name {
+			return true
+		}
+	}
+
+	return false
+}
+
+// addTagGroup adds the specified tag to the tag group extension. If the group doesn't exist, it is
+// created. If not, it's appended to the tag list.
+func addTagGroup(doc *openapi3.T, name, tag string) error {
+	key := "x-tagGroups"
+	var groups *XTagGroups
+
+	// Ensure the extension exists first.
+	foundGroups, ok := doc.ExtensionProps.Extensions[key]
+	if !ok {
+		groups = new(XTagGroups)
+		doc.ExtensionProps.Extensions[key] = groups
+	} else {
+		// If it's found, set the pointer
+		groups, ok = foundGroups.(*XTagGroups)
+		if !ok {
+			return fmt.Errorf("x-tagGroups is not a valid format: %#v", foundGroups)
+		}
+	}
+
+	group := groups.find(name)
+	if group == nil {
+		*groups = append(*groups, &XTagGroup{
+			Name: name,
+			Tags: []string{tag},
+		})
+	} else {
+		// Check if tag exists on group
+		if !group.tagExists(tag) {
+			group.Tags = append(group.Tags, tag)
+		}
+	}
+
+	return nil
+}
diff --git a/main.go b/main.go
@@ -27,9 +27,6 @@ func main() {
 	}
 
 	opts.Run(func(plugin *protogen.Plugin) error {
-		// Enable "optional" keyword in front of type. (e.g. optional string label = 1;)
-		// plugin.SupportedFeatures = uint64(pluginpb.CodeGeneratorResponse_FEATURE_PROTO3_OPTIONAL)
-
 		return generator.New(plugin, conf).Run()
 	})
 }

Original file line number	Diff line number	Diff line change
`@@ -14,6 +14,7 @@ extend google.protobuf.FieldOptions {`
`14`	`14`	`// comments.`
`15`	`15`	`string example = 5151;`
`16`	`16`
	`17`	`+ // Options for a field.`
`17`	`18`	`FieldOptions options = 5152;`
`18`	`19`	`}`
`19`	`20`
Original file line number	Diff line number	Diff line change
`@@ -29,4 +29,8 @@ message ServiceOptions {`
`29`	`29`	`// Sets the "x-displayName" extension property for the OAPI tag. This is used`
`30`	`30`	`// by redocly/redoc for a friendly tag name.`
`31`	`31`	`string display_name = 5;`
	`32`	`+`
	`33`	`+ // Adds the service to the extension x-tagGroups. If the group doesn't exist,`
	`34`	`+ // it is created and the service tag is added to it.`
	`35`	`+ string tag_group = 6;`
`32`	`36`	`}`