express-openapi icon indicating copy to clipboard operation
express-openapi copied to clipboard

Add support for tags

Open samishal1998 opened this issue 1 year ago • 2 comments

Tags are very helpful in APIs that have alot of endpoints https://swagger.io/docs/specification/grouping-operations-with-tags/

samishal1998 avatar Sep 16 '24 11:09 samishal1998

PR Welcome!

wesleytodd avatar Jan 16 '25 19:01 wesleytodd

Looked into this a little bit and it seems to be an issue with SwaggerUI and not Express OpenAPI (see: https://github.com/swagger-api/swagger-ui/issues/5653). Using tags as an array of strings does not lead to any issues, but using tags as an array of objects results in a tag which looks like: Image even though the JSON schema provided for tags (shown below) matches the example provided in: https://swagger.io/docs/specification/v3_0/grouping-operations-with-tags/

"tags": [
  {
    "name": "users",
    "description": "Users Desc",
    "externalDocs": {
      "url": "http://not-a-real-url.com/user-desc"
    }
  }
]

I added tests locally to confirm the tags are being passed properly which I can make a PR for if desired, but they seem to be passed to the schema without any modifications to the user's definition on this line: https://github.com/wesleytodd/express-openapi/blob/b56f6ee4d38d74095417968ae996c17a22e2cd92/lib/generate-doc.js#L26 so I am unsure if a test is actually needed...

Megapixel99 avatar Feb 07 '25 16:02 Megapixel99