diff --git a/docs/de/docs/index.md b/docs/de/docs/index.md new file mode 100644 index 000000000..3b8bb6371 --- /dev/null +++ b/docs/de/docs/index.md @@ -0,0 +1,467 @@ + +{!../../../docs/missing-translation.md!} + + +

+ FastAPI +

+

+ FastAPI framework, high performance, easy to learn, fast to code, ready for production +

+

+ + Test + + + Coverage + + + Package version + +

+ +--- + +**Documentation**: https://fastapi.tiangolo.com + +**Source Code**: https://github.com/tiangolo/fastapi + +--- + +FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.6+ based on standard Python type hints. + +The key features are: + +* **Fast**: Very high performance, on par with **NodeJS** and **Go** (thanks to Starlette and Pydantic). [One of the fastest Python frameworks available](#performance). + +* **Fast to code**: Increase the speed to develop features by about 200% to 300%. * +* **Fewer bugs**: Reduce about 40% of human (developer) induced errors. * +* **Intuitive**: Great editor support. Completion everywhere. Less time debugging. +* **Easy**: Designed to be easy to use and learn. Less time reading docs. +* **Short**: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs. +* **Robust**: Get production-ready code. With automatic interactive documentation. +* **Standards-based**: Based on (and fully compatible with) the open standards for APIs: OpenAPI (previously known as Swagger) and JSON Schema. + +* estimation based on tests on an internal development team, building production applications. + +## Sponsors + + + +{% if sponsors %} +{% for sponsor in sponsors.gold -%} + +{% endfor -%} +{%- for sponsor in sponsors.silver -%} + +{% endfor %} +{% endif %} + + + +Other sponsors + +## Opinions + +"_[...] I'm using **FastAPI** a ton these days. [...] I'm actually planning to use it for all of my team's **ML services at Microsoft**. Some of them are getting integrated into the core **Windows** product and some **Office** products._" + +
Kabir Khan - Microsoft (ref)
+ +--- + +"_We adopted the **FastAPI** library to spawn a **REST** server that can be queried to obtain **predictions**. [for Ludwig]_" + +
Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - Uber (ref)
+ +--- + +"_**Netflix** is pleased to announce the open-source release of our **crisis management** orchestration framework: **Dispatch**! [built with **FastAPI**]_" + +
Kevin Glisson, Marc Vilanova, Forest Monsen - Netflix (ref)
+ +--- + +"_I’m over the moon excited about **FastAPI**. It’s so fun!_" + +
Brian Okken - Python Bytes podcast host (ref)
+ +--- + +"_Honestly, what you've built looks super solid and polished. In many ways, it's what I wanted **Hug** to be - it's really inspiring to see someone build that._" + +
Timothy Crosley - Hug creator (ref)
+ +--- + +"_If you're looking to learn one **modern framework** for building REST APIs, check out **FastAPI** [...] It's fast, easy to use and easy to learn [...]_" + +"_We've switched over to **FastAPI** for our **APIs** [...] I think you'll like it [...]_" + +
Ines Montani - Matthew Honnibal - Explosion AI founders - spaCy creators (ref) - (ref)
+ +--- + +## **Typer**, the FastAPI of CLIs + + + +If you are building a CLI app to be used in the terminal instead of a web API, check out **Typer**. + +**Typer** is FastAPI's little sibling. And it's intended to be the **FastAPI of CLIs**. ⌨️ 🚀 + +## Requirements + +Python 3.6+ + +FastAPI stands on the shoulders of giants: + +* Starlette for the web parts. +* Pydantic for the data parts. + +## Installation + +
+ +```console +$ pip install fastapi + +---> 100% +``` + +
+ +You will also need an ASGI server, for production such as Uvicorn or Hypercorn. + +
+ +```console +$ pip install uvicorn[standard] + +---> 100% +``` + +
+ +## Example + +### Create it + +* Create a file `main.py` with: + +```Python +from typing import Optional + +from fastapi import FastAPI + +app = FastAPI() + + +@app.get("/") +def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +def read_item(item_id: int, q: Optional[str] = None): + return {"item_id": item_id, "q": q} +``` + +
+Or use async def... + +If your code uses `async` / `await`, use `async def`: + +```Python hl_lines="9 14" +from typing import Optional + +from fastapi import FastAPI + +app = FastAPI() + + +@app.get("/") +async def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +async def read_item(item_id: int, q: Optional[str] = None): + return {"item_id": item_id, "q": q} +``` + +**Note**: + +If you don't know, check the _"In a hurry?"_ section about `async` and `await` in the docs. + +
+ +### Run it + +Run the server with: + +
+ +```console +$ uvicorn main:app --reload + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +INFO: Started reloader process [28720] +INFO: Started server process [28722] +INFO: Waiting for application startup. +INFO: Application startup complete. +``` + +
+ +
+About the command uvicorn main:app --reload... + +The command `uvicorn main:app` refers to: + +* `main`: the file `main.py` (the Python "module"). +* `app`: the object created inside of `main.py` with the line `app = FastAPI()`. +* `--reload`: make the server restart after code changes. Only do this for development. + +
+ +### Check it + +Open your browser at http://127.0.0.1:8000/items/5?q=somequery. + +You will see the JSON response as: + +```JSON +{"item_id": 5, "q": "somequery"} +``` + +You already created an API that: + +* Receives HTTP requests in the _paths_ `/` and `/items/{item_id}`. +* Both _paths_ take `GET` operations (also known as HTTP _methods_). +* The _path_ `/items/{item_id}` has a _path parameter_ `item_id` that should be an `int`. +* The _path_ `/items/{item_id}` has an optional `str` _query parameter_ `q`. + +### Interactive API docs + +Now go to http://127.0.0.1:8000/docs. + +You will see the automatic interactive API documentation (provided by Swagger UI): + +![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) + +### Alternative API docs + +And now, go to http://127.0.0.1:8000/redoc. + +You will see the alternative automatic documentation (provided by ReDoc): + +![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) + +## Example upgrade + +Now modify the file `main.py` to receive a body from a `PUT` request. + +Declare the body using standard Python types, thanks to Pydantic. + +```Python hl_lines="4 9-12 25-27" +from typing import Optional + +from fastapi import FastAPI +from pydantic import BaseModel + +app = FastAPI() + + +class Item(BaseModel): + name: str + price: float + is_offer: Optional[bool] = None + + +@app.get("/") +def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +def read_item(item_id: int, q: Optional[str] = None): + return {"item_id": item_id, "q": q} + + +@app.put("/items/{item_id}") +def update_item(item_id: int, item: Item): + return {"item_name": item.name, "item_id": item_id} +``` + +The server should reload automatically (because you added `--reload` to the `uvicorn` command above). + +### Interactive API docs upgrade + +Now go to http://127.0.0.1:8000/docs. + +* The interactive API documentation will be automatically updated, including the new body: + +![Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) + +* Click on the button "Try it out", it allows you to fill the parameters and directly interact with the API: + +![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-04-swagger-03.png) + +* Then click on the "Execute" button, the user interface will communicate with your API, send the parameters, get the results and show them on the screen: + +![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-05-swagger-04.png) + +### Alternative API docs upgrade + +And now, go to http://127.0.0.1:8000/redoc. + +* The alternative documentation will also reflect the new query parameter and body: + +![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) + +### Recap + +In summary, you declare **once** the types of parameters, body, etc. as function parameters. + +You do that with standard modern Python types. + +You don't have to learn a new syntax, the methods or classes of a specific library, etc. + +Just standard **Python 3.6+**. + +For example, for an `int`: + +```Python +item_id: int +``` + +or for a more complex `Item` model: + +```Python +item: Item +``` + +...and with that single declaration you get: + +* Editor support, including: + * Completion. + * Type checks. +* Validation of data: + * Automatic and clear errors when the data is invalid. + * Validation even for deeply nested JSON objects. +* Conversion of input data: coming from the network to Python data and types. Reading from: + * JSON. + * Path parameters. + * Query parameters. + * Cookies. + * Headers. + * Forms. + * Files. +* Conversion of output data: converting from Python data and types to network data (as JSON): + * Convert Python types (`str`, `int`, `float`, `bool`, `list`, etc). + * `datetime` objects. + * `UUID` objects. + * Database models. + * ...and many more. +* Automatic interactive API documentation, including 2 alternative user interfaces: + * Swagger UI. + * ReDoc. + +--- + +Coming back to the previous code example, **FastAPI** will: + +* Validate that there is an `item_id` in the path for `GET` and `PUT` requests. +* Validate that the `item_id` is of type `int` for `GET` and `PUT` requests. + * If it is not, the client will see a useful, clear error. +* Check if there is an optional query parameter named `q` (as in `http://127.0.0.1:8000/items/foo?q=somequery`) for `GET` requests. + * As the `q` parameter is declared with `= None`, it is optional. + * Without the `None` it would be required (as is the body in the case with `PUT`). +* For `PUT` requests to `/items/{item_id}`, Read the body as JSON: + * Check that it has a required attribute `name` that should be a `str`. + * Check that it has a required attribute `price` that has to be a `float`. + * Check that it has an optional attribute `is_offer`, that should be a `bool`, if present. + * All this would also work for deeply nested JSON objects. +* Convert from and to JSON automatically. +* Document everything with OpenAPI, that can be used by: + * Interactive documentation systems. + * Automatic client code generation systems, for many languages. +* Provide 2 interactive documentation web interfaces directly. + +--- + +We just scratched the surface, but you already get the idea of how it all works. + +Try changing the line with: + +```Python + return {"item_name": item.name, "item_id": item_id} +``` + +...from: + +```Python + ... "item_name": item.name ... +``` + +...to: + +```Python + ... "item_price": item.price ... +``` + +...and see how your editor will auto-complete the attributes and know their types: + +![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png) + +For a more complete example including more features, see the Tutorial - User Guide. + +**Spoiler alert**: the tutorial - user guide includes: + +* Declaration of **parameters** from other different places as: **headers**, **cookies**, **form fields** and **files**. +* How to set **validation constraints** as `maximum_length` or `regex`. +* A very powerful and easy to use **Dependency Injection** system. +* Security and authentication, including support for **OAuth2** with **JWT tokens** and **HTTP Basic** auth. +* More advanced (but equally easy) techniques for declaring **deeply nested JSON models** (thanks to Pydantic). +* Many extra features (thanks to Starlette) as: + * **WebSockets** + * **GraphQL** + * extremely easy tests based on `requests` and `pytest` + * **CORS** + * **Cookie Sessions** + * ...and more. + +## Performance + +Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as one of the fastest Python frameworks available, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*) + +To understand more about it, see the section Benchmarks. + +## Optional Dependencies + +Used by Pydantic: + +* ujson - for faster JSON "parsing". +* email_validator - for email validation. + +Used by Starlette: + +* requests - Required if you want to use the `TestClient`. +* aiofiles - Required if you want to use `FileResponse` or `StaticFiles`. +* jinja2 - Required if you want to use the default template configuration. +* python-multipart - Required if you want to support form "parsing", with `request.form()`. +* itsdangerous - Required for `SessionMiddleware` support. +* pyyaml - Required for Starlette's `SchemaGenerator` support (you probably don't need it with FastAPI). +* graphene - Required for `GraphQLApp` support. +* ujson - Required if you want to use `UJSONResponse`. + +Used by FastAPI / Starlette: + +* uvicorn - for the server that loads and serves your application. +* orjson - Required if you want to use `ORJSONResponse`. + +You can install all of these with `pip install fastapi[all]`. + +## License + +This project is licensed under the terms of the MIT license. diff --git a/docs/de/mkdocs.yml b/docs/de/mkdocs.yml new file mode 100644 index 000000000..a00316687 --- /dev/null +++ b/docs/de/mkdocs.yml @@ -0,0 +1,125 @@ +site_name: FastAPI +site_description: FastAPI framework, high performance, easy to learn, fast to code, ready for production +site_url: https://fastapi.tiangolo.com/de/ +theme: + name: material + custom_dir: overrides + palette: + - scheme: default + primary: teal + accent: amber + toggle: + icon: material/lightbulb-outline + name: Switch to light mode + - scheme: slate + primary: teal + accent: amber + toggle: + icon: material/lightbulb + name: Switch to dark mode + features: + - search.suggest + - search.highlight + icon: + repo: fontawesome/brands/github-alt + logo: https://fastapi.tiangolo.com/img/icon-white.svg + favicon: https://fastapi.tiangolo.com/img/favicon.png + language: de +repo_name: tiangolo/fastapi +repo_url: https://github.com/tiangolo/fastapi +edit_uri: '' +google_analytics: +- UA-133183413-1 +- auto +plugins: +- search +- markdownextradata: + data: data +nav: +- FastAPI: index.md +- Languages: + - en: / + - de: /de/ + - es: /es/ + - fr: /fr/ + - id: /id/ + - it: /it/ + - ja: /ja/ + - ko: /ko/ + - pl: /pl/ + - pt: /pt/ + - ru: /ru/ + - sq: /sq/ + - tr: /tr/ + - uk: /uk/ + - zh: /zh/ +markdown_extensions: +- toc: + permalink: true +- markdown.extensions.codehilite: + guess_lang: false +- markdown_include.include: + base_path: docs +- admonition +- codehilite +- extra +- pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_div_format '' +- pymdownx.tabbed +extra: + social: + - icon: fontawesome/brands/github-alt + link: https://github.com/tiangolo/fastapi + - icon: fontawesome/brands/discord + link: https://discord.gg/VQjSZaeJmf + - icon: fontawesome/brands/twitter + link: https://twitter.com/tiangolo + - icon: fontawesome/brands/linkedin + link: https://www.linkedin.com/in/tiangolo + - icon: fontawesome/brands/dev + link: https://dev.to/tiangolo + - icon: fontawesome/brands/medium + link: https://medium.com/@tiangolo + - icon: fontawesome/solid/globe + link: https://tiangolo.com + alternate: + - link: / + name: en - English + - link: /de/ + name: de + - link: /es/ + name: es - español + - link: /fr/ + name: fr - français + - link: /id/ + name: id + - link: /it/ + name: it - italiano + - link: /ja/ + name: ja - 日本語 + - link: /ko/ + name: ko - 한국어 + - link: /pl/ + name: pl + - link: /pt/ + name: pt - português + - link: /ru/ + name: ru - русский язык + - link: /sq/ + name: sq - shqip + - link: /tr/ + name: tr - Türkçe + - link: /uk/ + name: uk - українська мова + - link: /zh/ + name: zh - 汉语 +extra_css: +- https://fastapi.tiangolo.com/css/termynal.css +- https://fastapi.tiangolo.com/css/custom.css +extra_javascript: +- https://unpkg.com/mermaid@8.4.6/dist/mermaid.min.js +- https://fastapi.tiangolo.com/js/termynal.js +- https://fastapi.tiangolo.com/js/custom.js diff --git a/docs/de/overrides/.gitignore b/docs/de/overrides/.gitignore new file mode 100644 index 000000000..e69de29bb diff --git a/docs/en/mkdocs.yml b/docs/en/mkdocs.yml index efb5378d1..d86ea1c39 100644 --- a/docs/en/mkdocs.yml +++ b/docs/en/mkdocs.yml @@ -39,6 +39,7 @@ nav: - FastAPI: index.md - Languages: - en: / + - de: /de/ - es: /es/ - fr: /fr/ - id: /id/ @@ -190,6 +191,8 @@ extra: alternate: - link: / name: en - English + - link: /de/ + name: de - link: /es/ name: es - español - link: /fr/ diff --git a/docs/es/mkdocs.yml b/docs/es/mkdocs.yml index 787decd1f..40c7c0ec4 100644 --- a/docs/es/mkdocs.yml +++ b/docs/es/mkdocs.yml @@ -39,6 +39,7 @@ nav: - FastAPI: index.md - Languages: - en: / + - de: /de/ - es: /es/ - fr: /fr/ - id: /id/ @@ -97,6 +98,8 @@ extra: alternate: - link: / name: en - English + - link: /de/ + name: de - link: /es/ name: es - español - link: /fr/ diff --git a/docs/fr/mkdocs.yml b/docs/fr/mkdocs.yml index 7ff24f8c4..3b98e3e3f 100644 --- a/docs/fr/mkdocs.yml +++ b/docs/fr/mkdocs.yml @@ -39,6 +39,7 @@ nav: - FastAPI: index.md - Languages: - en: / + - de: /de/ - es: /es/ - fr: /fr/ - id: /id/ @@ -95,6 +96,8 @@ extra: alternate: - link: / name: en - English + - link: /de/ + name: de - link: /es/ name: es - español - link: /fr/ diff --git a/docs/id/mkdocs.yml b/docs/id/mkdocs.yml index 1868aac8c..ed716124f 100644 --- a/docs/id/mkdocs.yml +++ b/docs/id/mkdocs.yml @@ -39,12 +39,14 @@ nav: - FastAPI: index.md - Languages: - en: / + - de: /de/ - es: /es/ - fr: /fr/ - id: /id/ - it: /it/ - ja: /ja/ - ko: /ko/ + - pl: /pl/ - pt: /pt/ - ru: /ru/ - sq: /sq/ @@ -86,6 +88,8 @@ extra: alternate: - link: / name: en - English + - link: /de/ + name: de - link: /es/ name: es - español - link: /fr/ @@ -98,6 +102,8 @@ extra: name: ja - 日本語 - link: /ko/ name: ko - 한국어 + - link: /pl/ + name: pl - link: /pt/ name: pt - português - link: /ru/ diff --git a/docs/it/mkdocs.yml b/docs/it/mkdocs.yml index 2b057b67e..11f7fe357 100644 --- a/docs/it/mkdocs.yml +++ b/docs/it/mkdocs.yml @@ -39,6 +39,7 @@ nav: - FastAPI: index.md - Languages: - en: / + - de: /de/ - es: /es/ - fr: /fr/ - id: /id/ @@ -87,6 +88,8 @@ extra: alternate: - link: / name: en - English + - link: /de/ + name: de - link: /es/ name: es - español - link: /fr/ diff --git a/docs/ja/mkdocs.yml b/docs/ja/mkdocs.yml index e083de096..ee69e49f8 100644 --- a/docs/ja/mkdocs.yml +++ b/docs/ja/mkdocs.yml @@ -39,6 +39,7 @@ nav: - FastAPI: index.md - Languages: - en: / + - de: /de/ - es: /es/ - fr: /fr/ - id: /id/ @@ -126,6 +127,8 @@ extra: alternate: - link: / name: en - English + - link: /de/ + name: de - link: /es/ name: es - español - link: /fr/ diff --git a/docs/ko/mkdocs.yml b/docs/ko/mkdocs.yml index 8768d61a2..f11333f3e 100644 --- a/docs/ko/mkdocs.yml +++ b/docs/ko/mkdocs.yml @@ -39,6 +39,7 @@ nav: - FastAPI: index.md - Languages: - en: / + - de: /de/ - es: /es/ - fr: /fr/ - id: /id/ @@ -93,6 +94,8 @@ extra: alternate: - link: / name: en - English + - link: /de/ + name: de - link: /es/ name: es - español - link: /fr/ diff --git a/docs/pl/mkdocs.yml b/docs/pl/mkdocs.yml index a2c6102b8..749d22938 100644 --- a/docs/pl/mkdocs.yml +++ b/docs/pl/mkdocs.yml @@ -39,8 +39,10 @@ nav: - FastAPI: index.md - Languages: - en: / + - de: /de/ - es: /es/ - fr: /fr/ + - id: /id/ - it: /it/ - ja: /ja/ - ko: /ko/ @@ -86,10 +88,14 @@ extra: alternate: - link: / name: en - English + - link: /de/ + name: de - link: /es/ name: es - español - link: /fr/ name: fr - français + - link: /id/ + name: id - link: /it/ name: it - italiano - link: /ja/ diff --git a/docs/pt/mkdocs.yml b/docs/pt/mkdocs.yml index e4f3a62d9..b1fa273cf 100644 --- a/docs/pt/mkdocs.yml +++ b/docs/pt/mkdocs.yml @@ -39,6 +39,7 @@ nav: - FastAPI: index.md - Languages: - en: / + - de: /de/ - es: /es/ - fr: /fr/ - id: /id/ @@ -100,6 +101,8 @@ extra: alternate: - link: / name: en - English + - link: /de/ + name: de - link: /es/ name: es - español - link: /fr/ diff --git a/docs/ru/mkdocs.yml b/docs/ru/mkdocs.yml index ca3feedef..6db8fe33d 100644 --- a/docs/ru/mkdocs.yml +++ b/docs/ru/mkdocs.yml @@ -39,6 +39,7 @@ nav: - FastAPI: index.md - Languages: - en: / + - de: /de/ - es: /es/ - fr: /fr/ - id: /id/ @@ -87,6 +88,8 @@ extra: alternate: - link: / name: en - English + - link: /de/ + name: de - link: /es/ name: es - español - link: /fr/ diff --git a/docs/sq/mkdocs.yml b/docs/sq/mkdocs.yml index 77de29e13..8ebf80358 100644 --- a/docs/sq/mkdocs.yml +++ b/docs/sq/mkdocs.yml @@ -39,6 +39,7 @@ nav: - FastAPI: index.md - Languages: - en: / + - de: /de/ - es: /es/ - fr: /fr/ - id: /id/ @@ -87,6 +88,8 @@ extra: alternate: - link: / name: en - English + - link: /de/ + name: de - link: /es/ name: es - español - link: /fr/ diff --git a/docs/tr/mkdocs.yml b/docs/tr/mkdocs.yml index 234aae178..660cb9238 100644 --- a/docs/tr/mkdocs.yml +++ b/docs/tr/mkdocs.yml @@ -39,6 +39,7 @@ nav: - FastAPI: index.md - Languages: - en: / + - de: /de/ - es: /es/ - fr: /fr/ - id: /id/ @@ -87,6 +88,8 @@ extra: alternate: - link: / name: en - English + - link: /de/ + name: de - link: /es/ name: es - español - link: /fr/ diff --git a/docs/uk/mkdocs.yml b/docs/uk/mkdocs.yml index 8ecf20d17..3fdd9825e 100644 --- a/docs/uk/mkdocs.yml +++ b/docs/uk/mkdocs.yml @@ -39,6 +39,7 @@ nav: - FastAPI: index.md - Languages: - en: / + - de: /de/ - es: /es/ - fr: /fr/ - id: /id/ @@ -87,6 +88,8 @@ extra: alternate: - link: / name: en - English + - link: /de/ + name: de - link: /es/ name: es - español - link: /fr/ diff --git a/docs/zh/mkdocs.yml b/docs/zh/mkdocs.yml index 359fb4e8f..5cfc07c6c 100644 --- a/docs/zh/mkdocs.yml +++ b/docs/zh/mkdocs.yml @@ -39,6 +39,7 @@ nav: - FastAPI: index.md - Languages: - en: / + - de: /de/ - es: /es/ - fr: /fr/ - id: /id/ @@ -133,6 +134,8 @@ extra: alternate: - link: / name: en - English + - link: /de/ + name: de - link: /es/ name: es - español - link: /fr/