Project name: soquestion
Project template: api
Use controllers? Yes
Use OpenAPI Documentation? Yes
Library to read settings essentials-configuration
App settings format YAMLЭто создаст простой API на основе BlackSheep с конечными точками, определенными в app/controllers/examples.py:
"""
Example API implemented using a controller.
"""
from typing import List, Optional
from blacksheep.server.controllers import Controller, get, post
class ExamplesController(Controller):
@classmethod
def route(cls) -> Optional[str]:
return "/api/examples"
@classmethod
def class_name(cls) -> str:
return "Examples"
@get()
async def get_examples(self) -> List[str]:
"""
Gets a list of examples.
Lorem Ipsum Dolor Sit amet
"""
return list(f"example {i}" for i in range(3))
@post()
async def add_example(self, example: str):
"""
Adds an example.
"""
При запуске API (не забудьте создать и активировать виртуальную среду перед установкой pip...) с помощью python dev.py и перейдите по адресу http://localhost:44777/docs, и вы увидите документацию OpenAPI.
Согласно документации, вы можете использовать строку документации для указания описания конечной точки.
Можно ли как-то добавить документацию для ответов?
Согласно документации вы можете использовать декоратор @docs, но это работает только в простом файле, где @docs определен заранее. В сгенерированном API @docs определен в app/docs/__init.py__, но я не могу найти способ использовать его внутри example.py.
Сгенерированный файл app/docs/__init.py__ выглядит следующим образом:
"""
This module contains OpenAPI Documentation definition for the API.
It exposes a docs object that can be used to decorate request handlers with additional
information, used to generate OpenAPI documentation.
"""
from blacksheep import Application
from blacksheep.server.openapi.v3 import OpenAPIHandler
from openapidocs.v3 import Info
from app.docs.binders import set_binders_docs
from app.settings import Settings
def configure_docs(app: Application, settings: Settings):
docs = OpenAPIHandler(
info=Info(title=settings.info.title, version=settings.info.version),
anonymous_access=True,
)
# include only endpoints whose path starts with "/api/"
docs.include = lambda path, _: path.startswith("/api/")
set_binders_docs(docs)
docs.bind_app(app)
Подробнее здесь: https://stackoverflow.com/questions/789 ... ksheep-api
