[Feature] Support for tag descriptions

[mattcrichards]

Is your feature request related to a problem? Please describe. We are using openapi tags to group endpoints together in the docs - which is great. The openapi spec allows for a description field that would give us the ability to describe a group of tags, which for us feels very important, as it leaves the per-endpoint descriptions room to be more precise.

https://swagger.io/docs/specification/grouping-operations-with-tags/

Describe the solution you'd like We'd like the ability to generate a tags section in our openapi.yml file (in-between info and paths) where in a name and description fields could live, along with the ability to control the values for those fields.

Describe alternatives you've considered Putting more verbose descriptions in each endpoint, and perhaps even manually adding the tags section to the openapi file.

Additional context

[dsinghvi]

@mattcrichards thanks for filing this issue! We used to have a concept of sections but several users didn't write enough documentation so the sections looked a bit weird, so we removed it. That being said I could see a world where we allow you to configure those sections on.

Do you have a link to your OAI spec/docs that we could take a look at?

[mattcrichards]

Thanks for your quick response, @dsinghvi !

Unfortunately I cannot share our OAI spec/docs but if it would increase the likelihood that support for this standard OAI property was added, I would certainly draft up a dummy.

[mattcrichards]

@dsinghvi - An example file is below. Please let me know if this is something you think the team will include, as we'd love to use fern to build tag descriptions into our openapi.yml file.

openapi: 3.0.0
info:
  title: Tag Descriptions
  description: Having tag descriptions is very helpful
  version: 1.0.0

servers:
  - url: http://localhost:8000
    description: Local development server

tags:
  - name: shapes
    description: Shapes are graphical representations of an object's form or its external boundary, outline, or external surface.
  - name: colors
    description: Colors are the aspect of things that is caused by differing qualities of light being reflected or emitted by them.

paths:
  /shapes/circle:
    get:
      tags: 
        - shapes
      description: A circle is a shape with no corners.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              example:
                message: "Hello, world!"
  /shapes/square:
    get:
      tags: 
        - shapes
      description: A square is a shape with four corners.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              example:
                message: "Hello, world!"

  /colors/red:
    get:
      tags: 
        - colors
      description: Red is a color that sometimes means "stop."
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              example:
                message: "Hello, world!"
  /colors/green:
    get:
      tags: 
        - colors
      description: Green is a color that sometimes means "go."
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              example:
                message: "Hello, world!"

components:
  schemas:
    Example:
      type: object
      properties:
        message:
          type: string