Add description for tags

[tyzhnenko]

Tags ordering can be handled via tags description field [1]

docs = OpenAPIHandler(
    info=Info(title="Example API", version="0.0.1"),
    tags=[
        Tag(name="Users"),
        Tag(name="Favorites"),
        Tag(name="Reactions"),
        Tag(name="Topics"),
        Tag(name="Reviews"),
        Tag(name="Comments"),
    ],
)
docs.bind_app(app)

For example, if a project has autogenerated tags in terms of using ApiController. OpenAPIHandler will automatically sort tags alphabetically.

from dataclasses import dataclass

from blacksheep import Application
from blacksheep.server.controllers import APIController, get, post
from blacksheep.server.openapi.v3 import OpenAPIHandler
from openapidocs.v3 import Info

app = Application()

docs = OpenAPIHandler(info=Info(title="Example API", version="0.0.1"))
docs.bind_app(app)

@dataclass
class Cat:
    pass

@dataclass
class Dog:
    pass

@dataclass
class Parrot:
    pass

class Cats(APIController):
    @get()
    def get_cats(self) -> list[Cat]:
        """Return the list of configured cats."""

    @post()
    def create_cat(self, cat: Cat) -> None:
        """Add a Cat to the system."""

class Dogs(APIController):
    @get()
    def get_dogs(self) -> list[Dog]:
        """Return the list of configured dogs."""

    @post()
    def create_dog(self, dog: Dog) -> None:
        """Add a Dog to the system."""

class Parrots(APIController):
    @get()
    def get_parrots(self) -> list[Parrot]:
        """Return the list of configured Parrots."""

    @post()
    def create_parrot(self, parrot: Parrot) -> None:
        """Add a Parrot to the system."""

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

Issue: #327

[RobertoPrevato]

This is very good, thanks you @tyzhnenko. I'm willing to merge your PR, as I wrote in the linked issue. I recommend one more thing, I try to prepare an example later tonight. 😄

[tyzhnenko]

@RobertoPrevato I've updated my PR please take a look when you have time to do that. by the way, it seems the new release of setuptools breaks the project pipelines.

[RobertoPrevato]

@tyzhnenko I merge your PR. I started looking into the build issues, I fix them later. Thanks again for your help! By the way, I had a wonderful idea on how to improve the development experience with BlackSheep - something I didn´t like myself. I share it soon. :)