Merge pull request #123 from 0b01001001/dev

support tag description and external doc url

examples/falcon_demo.py

@@ -6,14 +6,16 @@
 import falcon
 from pydantic import BaseModel, Field
 
-from spectree import Response, SpecTree
+from spectree import Response, SpecTree, Tag
 
 api = SpecTree(
     "falcon",
     title="Demo Service",
     version="0.1.2",
 )
 
+demo = Tag(name="demo", description="😊", externalDocs={"url": "https://github.com"})
+
 
 class Query(BaseModel):
     text: str = Field(
@@ -51,7 +53,7 @@ class Ping:
     def check(self):
         pass
 
-    @api.validate(tags=["demo"])
+    @api.validate(tags=[demo])
     def on_get(self, req, resp):
         """
         health check
@@ -66,7 +68,7 @@ class Classification:
     classification demo
     """
 
-    @api.validate(tags=["demo"])
+    @api.validate(tags=[demo])
     def on_get(self, req, resp, source, target):
         """
         API summary

setup.py

@@ -14,7 +14,7 @@
 
 setup(
     name="spectree",
-    version="0.4.2",
+    version="0.4.3",
     author="Keming Yang",
     author_email="[email protected]",
     description=(

spectree/__init__.py

@@ -1,9 +1,10 @@
 import logging
 
+from .models import Tag
 from .response import Response
 from .spec import SpecTree
 
-__all__ = ["SpecTree", "Response"]
+__all__ = ["SpecTree", "Response", "Tag"]
 
 # setup library logging
 logging.getLogger(__name__).addHandler(logging.NullHandler())

spectree/models.py

@@ -0,0 +1,46 @@
+from typing import Any, Dict, Sequence
+
+from pydantic import BaseModel, Field
+
+
+class ExternalDocs(BaseModel):
+    description: str = ""
+    url: str
+
+
+class Tag(BaseModel):
+    """OpenAPI tag object"""
+
+    name: str
+    description: str = ""
+    externalDocs: ExternalDocs = None
+
+    def __str__(self):
+        return self.name
+
+
+class UnprocessableEntityElement(BaseModel):
+    """Model of missing field description."""
+
+    loc: Sequence[str] = Field(
+        ...,
+        title="Missing field name",
+    )
+    msg: str = Field(
+        ...,
+        title="Error message",
+    )
+    type: str = Field(  # noqa: WPS125
+        ...,
+        title="Error type",
+    )
+    ctx: Dict[str, Any] = Field(
+        None,
+        title="Error context",
+    )
+
+
+class UnprocessableEntity(BaseModel):
+    """Model of 422 Unprocessable Entity error."""
+
+    __root__: Sequence[UnprocessableEntityElement]

spectree/response.py

@@ -1,37 +1,9 @@
-from typing import Any, Dict, Sequence
-
-from pydantic import BaseModel, Field
+from pydantic import BaseModel
 
+from .models import UnprocessableEntity
 from .utils import parse_code
 
 
-class UnprocessableEntityElement(BaseModel):
-    """Model of missing field description."""
-
-    loc: Sequence[str] = Field(
-        ...,
-        title="Missing field name",
-    )
-    msg: str = Field(
-        ...,
-        title="Error message",
-    )
-    type: str = Field(  # noqa: WPS125
-        ...,
-        title="Error type",
-    )
-    ctx: Dict[str, Any] = Field(
-        None,
-        title="Error context",
-    )
-
-
-class UnprocessableEntity(BaseModel):
-    """Model of 422 Unprocessable Entity error."""
-
-    __root__: Sequence[UnprocessableEntityElement]
-
-
 class Response:
     """
     response object

spectree/spec.py

@@ -3,6 +3,7 @@
 from pydantic import BaseModel
 
 from .config import Config
+from .models import Tag
 from .plugins import PLUGINS
 from .utils import (
     default_after_handler,
@@ -113,7 +114,7 @@ def validate(
         :param headers: `pydantic.BaseModel`, if you have specific headers
         :param cookies: `pydantic.BaseModel`, if you have cookies for this route
         :param resp: `spectree.Response`
-        :param tags: a tuple of tags string
+        :param tags: a tuple of strings or :class:`spectree.models.Tag`
         :param before: :meth:`spectree.utils.default_before_handler` for
             specific endpoint
         :param after: :meth:`spectree.utils.default_after_handler` for
@@ -208,14 +209,16 @@ def _generate_spec(self):
                 summary, desc = parse_comments(func)
                 func_tags = getattr(func, "tags", ())
                 for tag in func_tags:
-                    if tag not in tags:
-                        tags[tag] = {"name": tag}
+                    if str(tag) not in tags:
+                        tags[str(tag)] = (
+                            tag.dict() if isinstance(tag, Tag) else {"name": tag}
+                        )
 
                 routes[path][method.lower()] = {
                     "summary": summary or f"{name} <{method}>",
                     "operationId": f"{method.lower()}_{path}",
                     "description": desc or "",
-                    "tags": getattr(func, "tags", []),
+                    "tags": [str(x) for x in getattr(func, "tags", ())],
                     "parameters": parse_params(func, parameters[:], self.models),
                     "responses": parse_resp(func),
                 }

tests/common.py

@@ -3,6 +3,10 @@
 
 from pydantic import BaseModel, Field, root_validator
 
+from spectree import Tag
+
+api_tag = Tag(name="API", description="🐱", externalDocs={"url": "https://pypi.org"})
+
 
 class Order(IntEnum):
     asce = 1

tests/test_plugin.py

@@ -19,7 +19,18 @@ def test_plugin_spec(api):
     for name, schema in models.items():
         assert api.spec["components"]["schemas"][name] == schema
 
-    assert api.spec["tags"] == [{"name": tag} for tag in ("test", "health", "api")]
+    assert api.spec["tags"] == [
+        {"name": "test"},
+        {"name": "health"},
+        {
+            "description": "🐱",
+            "externalDocs": {
+                "description": "",
+                "url": "https://pypi.org",
+            },
+            "name": "API",
+        },
+    ]
 
     assert get_paths(api.spec) == [
         "/api/user/{name}",
@@ -35,7 +46,7 @@ def test_plugin_spec(api):
     assert ping["operationId"] == "get_/ping"
 
     user = api.spec["paths"]["/api/user/{name}"]["post"]
-    assert user["tags"] == ["api", "test"]
+    assert user["tags"] == ["API", "test"]
     assert (
         user["requestBody"]["content"]["application/json"]["schema"]["$ref"]
         == "#/components/schemas/JSON"

tests/test_plugin_falcon.py

@@ -10,7 +10,7 @@
 
 from spectree import Response, SpecTree
 
-from .common import JSON, Cookies, Headers, Query, Resp, StrDict
+from .common import JSON, Cookies, Headers, Query, Resp, StrDict, api_tag
 
 
 def before_handler(req, resp, err, instance):
@@ -54,7 +54,7 @@ def on_get(self, req, resp, name):
         json=JSON,
         cookies=Cookies,
         resp=Response(HTTP_200=Resp, HTTP_401=None),
-        tags=["api", "test"],
+        tags=[api_tag, "test"],
     )
     def on_post(self, req, resp, name):
         score = [randint(0, req.context.json.limit) for _ in range(5)]
@@ -77,7 +77,7 @@ def on_get(self, req, resp, name):
 
     @api.validate(
         resp=Response(HTTP_200=Resp, HTTP_401=None),
-        tags=["api", "test"],
+        tags=[api_tag, "test"],
     )
     def on_post(self, req, resp, name, query: Query, json: JSON, cookies: Cookies):
         score = [randint(0, req.context.json.limit) for _ in range(5)]

tests/test_plugin_flask.py

@@ -6,7 +6,7 @@
 
 from spectree import Response, SpecTree
 
-from .common import JSON, Cookies, Headers, Query, Resp, StrDict
+from .common import JSON, Cookies, Headers, Query, Resp, StrDict, api_tag
 
 
 def before_handler(req, resp, err, _):
@@ -41,7 +41,7 @@ def ping():
     json=JSON,
     cookies=Cookies,
     resp=Response(HTTP_200=Resp, HTTP_401=None),
-    tags=["api", "test"],
+    tags=[api_tag, "test"],
     after=api_after_handler,
 )
 def user_score(name):
@@ -55,7 +55,7 @@ def user_score(name):
 @app.route("/api/user_annotated/<name>", methods=["POST"])
 @api.validate(
     resp=Response(HTTP_200=Resp, HTTP_401=None),
-    tags=["api", "test"],
+    tags=[api_tag, "test"],
     after=api_after_handler,
 )
 def user_score_annotated(name, query: Query, json: JSON, cookies: Cookies):

tests/test_plugin_flask_blueprint.py

@@ -6,7 +6,7 @@
 
 from spectree import Response, SpecTree
 
-from .common import JSON, Cookies, Headers, Query, Resp, StrDict
+from .common import JSON, Cookies, Headers, Query, Resp, StrDict, api_tag
 
 
 def before_handler(req, resp, err, _):
@@ -40,7 +40,7 @@ def ping():
     json=JSON,
     cookies=Cookies,
     resp=Response(HTTP_200=Resp, HTTP_401=None),
-    tags=["api", "test"],
+    tags=[api_tag, "test"],
     after=api_after_handler,
 )
 def user_score(name):
@@ -54,7 +54,7 @@ def user_score(name):
 @app.route("/api/user_annotated/<name>", methods=["POST"])
 @api.validate(
     resp=Response(HTTP_200=Resp, HTTP_401=None),
-    tags=["api", "test"],
+    tags=[api_tag, "test"],
     after=api_after_handler,
 )
 def user_score_annotated(name, query: Query, json: JSON, cookies: Cookies):

tests/test_plugin_flask_view.py

@@ -7,7 +7,7 @@
 
 from spectree import Response, SpecTree
 
-from .common import JSON, Cookies, Headers, Query, Resp, StrDict
+from .common import JSON, Cookies, Headers, Query, Resp, StrDict, api_tag
 
 
 def before_handler(req, resp, err, _):
@@ -44,7 +44,7 @@ class User(MethodView):
         json=JSON,
         cookies=Cookies,
         resp=Response(HTTP_200=Resp, HTTP_401=None),
-        tags=["api", "test"],
+        tags=[api_tag, "test"],
         after=api_after_handler,
     )
     def post(self, name):
@@ -58,7 +58,7 @@ def post(self, name):
 class UserAnnotated(MethodView):
     @api.validate(
         resp=Response(HTTP_200=Resp, HTTP_401=None),
-        tags=["api", "test"],
+        tags=[api_tag, "test"],
         after=api_after_handler,
     )
     def post(self, name, query: Query, json: JSON, cookies: Cookies):

tests/test_plugin_starlette.py

@@ -10,7 +10,7 @@
 
 from spectree import Response, SpecTree
 
-from .common import JSON, Cookies, Headers, Query, Resp, StrDict
+from .common import JSON, Cookies, Headers, Query, Resp, StrDict, api_tag
 
 
 def before_handler(req, resp, err, instance):
@@ -51,7 +51,7 @@ def get(self, request):
     json=JSON,
     cookies=Cookies,
     resp=Response(HTTP_200=Resp, HTTP_401=None),
-    tags=["api", "test"],
+    tags=[api_tag, "test"],
 )
 async def user_score(request):
     score = [randint(0, request.context.json.limit) for _ in range(5)]
@@ -63,7 +63,7 @@ async def user_score(request):
 
 @api.validate(
     resp=Response(HTTP_200=Resp, HTTP_401=None),
-    tags=["api", "test"],
+    tags=[api_tag, "test"],
 )
 async def user_score_annotated(request, query: Query, json: JSON, cookies: Cookies):
     score = [randint(0, json.limit) for _ in range(5)]

tests/test_utils.py

@@ -37,7 +37,6 @@ def demo_func_with_query():
 
     a description
     """
-    pass
 
 
 class DemoClass: