diff --git a/docs/en/docs/img/tutorial/metadata/image01.png b/docs/en/docs/img/tutorial/metadata/image01.png index e9800d53..b7708a3f 100644 Binary files a/docs/en/docs/img/tutorial/metadata/image01.png and b/docs/en/docs/img/tutorial/metadata/image01.png differ diff --git a/docs/en/docs/tutorial/metadata.md b/docs/en/docs/tutorial/metadata.md index 7ec30542..78f17031 100644 --- a/docs/en/docs/tutorial/metadata.md +++ b/docs/en/docs/tutorial/metadata.md @@ -2,21 +2,28 @@ You can customize several metadata configurations in your **FastAPI** application. -## Title, description, and version +## Metadata for API -You can set the: +You can set the following fields that are used in the OpenAPI specification and the automatic API docs UIs: -* **Title**: used as your API's title/name, in OpenAPI and the automatic API docs UIs. -* **Description**: the description of your API, in OpenAPI and the automatic API docs UIs. -* **Version**: the version of your API, e.g. `v2` or `2.5.0`. - * Useful for example if you had a previous version of the application, also using OpenAPI. +| Parameter | Type | Description | +|------------|------|-------------| +| `title` | `str` | The title of the API. | +| `description` | `str` | A short description of the API. It can use Markdown. | +| `version` | `string` | The version of the API. This is the version of your own application, not of OpenAPI. For example `2.5.0`. | +| `terms_of_service` | `str` | A URL to the Terms of Service for the API. If provided, this has to be a URL. | +| `contact` | `dict` | The contact information for the exposed API. It can contain several fields.
contact fields
ParameterTypeDescription
namestrThe identifying name of the contact person/organization.
urlstrThe URL pointing to the contact information. MUST be in the format of a URL.
emailstrThe email address of the contact person/organization. MUST be in the format of an email address.
| +| `license_info` | `dict` | The license information for the exposed API. It can contain several fields.
license_info fields
ParameterTypeDescription
namestrREQUIRED (if a license_info is set). The license name used for the API.
urlstrA URL to the license used for the API. MUST be in the format of a URL.
| -To set them, use the parameters `title`, `description`, and `version`: +You can set them as follows: -```Python hl_lines="4-6" +```Python hl_lines="3-16 19-31" {!../../../docs_src/metadata/tutorial001.py!} ``` +!!! tip + You can write Markdown in the `description` field and it will be rendered in the output. + With this configuration, the automatic API docs would look like: diff --git a/docs_src/metadata/tutorial001.py b/docs_src/metadata/tutorial001.py index 16bab8a0..3fba9e7d 100644 --- a/docs_src/metadata/tutorial001.py +++ b/docs_src/metadata/tutorial001.py @@ -1,12 +1,37 @@ from fastapi import FastAPI +description = """ +ChimichangApp API helps you do awesome stuff. 🚀 + +## Items + +You can **read items**. + +## Users + +You will be able to: + +* **Create users** (_not implemented_). +* **Read users** (_not implemented_). +""" + app = FastAPI( - title="My Super Project", - description="This is a very fancy project, with auto docs for the API and everything", - version="2.5.0", + title="ChimichangApp", + description=description, + version="0.0.1", + terms_of_service="http://example.com/terms/", + contact={ + "name": "Deadpoolio the Amazing", + "url": "http://x-force.example.com/contact/", + "email": "dp@x-force.example.com", + }, + license_info={ + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.html", + }, ) @app.get("/items/") async def read_items(): - return [{"name": "Foo"}] + return [{"name": "Katana"}] diff --git a/fastapi/applications.py b/fastapi/applications.py index 3f78238d..b013e7b4 100644 --- a/fastapi/applications.py +++ b/fastapi/applications.py @@ -55,6 +55,9 @@ class FastAPI(Starlette): ] = None, on_startup: Optional[Sequence[Callable[[], Any]]] = None, on_shutdown: Optional[Sequence[Callable[[], Any]]] = None, + terms_of_service: Optional[str] = None, + contact: Optional[Dict[str, Union[str, Any]]] = None, + license_info: Optional[Dict[str, Union[str, Any]]] = None, openapi_prefix: str = "", root_path: str = "", root_path_in_servers: bool = True, @@ -97,6 +100,9 @@ class FastAPI(Starlette): self.title = title self.description = description self.version = version + self.terms_of_service = terms_of_service + self.contact = contact + self.license_info = license_info self.servers = servers or [] self.openapi_url = openapi_url self.openapi_tags = openapi_tags @@ -132,6 +138,9 @@ class FastAPI(Starlette): version=self.version, openapi_version=self.openapi_version, description=self.description, + terms_of_service=self.terms_of_service, + contact=self.contact, + license_info=self.license_info, routes=self.routes, tags=self.openapi_tags, servers=self.servers, diff --git a/fastapi/openapi/utils.py b/fastapi/openapi/utils.py index 8dbe3902..604ba5b0 100644 --- a/fastapi/openapi/utils.py +++ b/fastapi/openapi/utils.py @@ -362,10 +362,19 @@ def get_openapi( routes: Sequence[BaseRoute], tags: Optional[List[Dict[str, Any]]] = None, servers: Optional[List[Dict[str, Union[str, Any]]]] = None, + terms_of_service: Optional[str] = None, + contact: Optional[Dict[str, Union[str, Any]]] = None, + license_info: Optional[Dict[str, Union[str, Any]]] = None, ) -> Dict[str, Any]: - info = {"title": title, "version": version} + info: Dict[str, Any] = {"title": title, "version": version} if description: info["description"] = description + if terms_of_service: + info["termsOfService"] = terms_of_service + if contact: + info["contact"] = contact + if license_info: + info["license"] = license_info output: Dict[str, Any] = {"openapi": openapi_version, "info": info} if servers: output["servers"] = servers diff --git a/tests/test_tutorial/test_metadata/test_tutorial001.py b/tests/test_tutorial/test_metadata/test_tutorial001.py index aae79dcc..b7281e29 100644 --- a/tests/test_tutorial/test_metadata/test_tutorial001.py +++ b/tests/test_tutorial/test_metadata/test_tutorial001.py @@ -7,21 +7,31 @@ client = TestClient(app) openapi_schema = { "openapi": "3.0.2", "info": { - "title": "My Super Project", - "version": "2.5.0", - "description": "This is a very fancy project, with auto docs for the API and everything", + "title": "ChimichangApp", + "description": "\nChimichangApp API helps you do awesome stuff. 🚀\n\n## Items\n\nYou can **read items**.\n\n## Users\n\nYou will be able to:\n\n* **Create users** (_not implemented_).\n* **Read users** (_not implemented_).\n", + "termsOfService": "http://example.com/terms/", + "contact": { + "name": "Deadpoolio the Amazing", + "url": "http://x-force.example.com/contact/", + "email": "dp@x-force.example.com", + }, + "license": { + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.html", + }, + "version": "0.0.1", }, "paths": { "/items/": { "get": { + "summary": "Read Items", + "operationId": "read_items_items__get", "responses": { "200": { "description": "Successful Response", "content": {"application/json": {"schema": {}}}, } }, - "summary": "Read Items", - "operationId": "read_items_items__get", } } }, @@ -37,4 +47,4 @@ def test_openapi_schema(): def test_items(): response = client.get("/items/") assert response.status_code == 200, response.text - assert response.json() == [{"name": "Foo"}] + assert response.json() == [{"name": "Katana"}]