Duplicate tags seen in Swagger Specification

[KowsikaRamachandran]

Hi,

I could see some duplicate tags in the open api spec inspite of custom tag names being added to all the rpcs under the service.

Service name tag seems to be a duplicate one. How to remove that tag from the open API spec?

Also, we don't want tags to be appearing in spec for services with no annotations. How to remove the tag name for services with no bindings in the proto?

[johanbrandhorst]

Could you share a reproducible example? That sounds like a bug if I'm understanding it correctly.

[KowsikaRamachandran]

Attached is the sample proto and swagger spec generated from that proto.
Downloads.zip

Also let me know how to disable tags getting added for unannotated service names in proto file

[johanbrandhorst]

I tried generating a swagger file using protoc-gen-openapiv2 from the protofile you provided and it looks like this:

{
  "swagger": "2.0",
  "info": {
    "title": "test.proto",
    "version": "version not set"
  },
  "tags": [
    {
      "name": "UserManagement"
    }
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {},
  "definitions": {
    "protobufAny": {
      "type": "object",
      "properties": {
        "typeUrl": {
          "type": "string"
        },
        "value": {
          "type": "string",
          "format": "byte"
        }
      }
    },
    "rpcStatus": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        },
        "details": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/protobufAny"
          }
        }
      }
    },
    "usersResponse": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string"
        }
      }
    }
  }
}

Note that it has no services since you haven't set any http.proto annotations in your protofile. I also notice a single tag. So I'm not sure where that YAML file is coming from, but protoc-gen-openapiv2 does not generate YAML files. What command are you using to generate this?

[KowsikaRamachandran]

HI,

Attached is the yaml file with http rules,
userManagement.zip

Command used for the swagger generation:
protoc --openapiv2_out=json_names_for_fields=false,logtostderr=true,allow_delete_body=true,grpc_api_configuration=./userManagement/userManagement.yaml:./SwaggerFiles --proto_path=./userManagement/ -I=./userManagement/ userManagement.proto

[johanbrandhorst]

I ran the generation command and this is my output:

{
  "swagger": "2.0",
  "info": {
    "title": "test.proto",
    "version": "version not set"
  },
  "tags": [
    {
      "name": "UserManagement"
    }
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/api/v2/user": {
      "delete": {
        "operationId": "UserManagement_deleteUser",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/usersResponse"
            }
          },
          "201": {
            "description": " Created : success status response code",
            "schema": {}
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/usersRequest"
            }
          }
        ],
        "tags": [
          "User Management"
        ]
      },
      "post": {
        "operationId": "UserManagement_addUser",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/usersResponse"
            }
          },
          "201": {
            "description": " Created : success status response code",
            "schema": {}
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/usersRequest"
            }
          }
        ],
        "tags": [
          "User Management"
        ]
      },
      "put": {
        "operationId": "UserManagement_updateUser",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/usersResponse"
            }
          },
          "204": {
            "description": " No Content: success status response code",
            "schema": {}
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/usersRequest"
            }
          }
        ],
        "tags": [
          "User Management"
        ]
      }
    }
  },
  "definitions": {
    "protobufAny": {
      "type": "object",
      "properties": {
        "type_url": {
          "type": "string"
        },
        "value": {
          "type": "string",
          "format": "byte"
        }
      }
    },
    "rpcStatus": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        },
        "details": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/protobufAny"
          }
        }
      }
    },
    "usersRequest": {
      "type": "object",
      "properties": {
        "user_name": {
          "type": "string"
        }
      }
    },
    "usersResponse": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string"
        }
      }
    }
  }
}

Is this incorrect? It looks fine to me, one top level tag and then the tags used within each message. How are you generating the swagger.yaml?

[KowsikaRamachandran]

Yes, thats the problem. Have you tried integrating above specification to swagger UI? I have integrated the above open API spec to swagger editor and attached is the screenshot of the same, We have one top level tag and tag used by each API. Thats not looking correct, duplicate top level tag is visible.

[johanbrandhorst]

Ah, I see, one of them has a space and one of them doesn't. Would it be okay for you to change your tag to UserManagement in the protobuf file? I expect the inferred tag comes from the service name.

[KowsikaRamachandran]

Hi,

But we want to use customized tag names and split APIs based on the customized tag under the same service in the proto file.

This issue is not seen in a_bit_of_everything.proto file. Can you check once from your side?

[johanbrandhorst]

I don't think we support not generating a tag per-service, which seems to be what you're asking for here? Would this be fixed by simply post-processing the swagger.json output? Presumably all you need to do is drop the UserManagement top level tag?

[KowsikaRamachandran]

Yes, We will do post-processing to drop service name tags. Thanks