From 80110dd99106914da31fbab545e50e7e2f6965f8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Mon, 10 Dec 2018 07:54:13 +0400 Subject: [PATCH] :memo: Update docs: features --- docs/features.md | 141 +++++++++++++++++++++++++++------- docs/index.md | 6 +- docs/tutorial/oauth2-jwt.md | 1 + docs/tutorial/python-types.md | 1 + mkdocs.yml | 2 +- 5 files changed, 119 insertions(+), 32 deletions(-) create mode 100644 docs/tutorial/oauth2-jwt.md create mode 100644 docs/tutorial/python-types.md diff --git a/docs/features.md b/docs/features.md index 96d706f0b..b35fa34b7 100644 --- a/docs/features.md +++ b/docs/features.md @@ -3,9 +3,18 @@ **FastAPI** gives you the following: -* Automatic API documentation with the open standard: OpenAPI. +### Based on open standards + +* OpenAPI for API creation, including declarations of endpoints, parameters, body requests, security, etc. * Automatic data model documentation with JSON Schema (as OpenAPI itself is based on JSON Schema). -* Interactive API documentation and exploration web user interface with Swagger UI. +* Designed around these standards, after a meticulous study. Instead of an afterthought layer on top. +* This also allows using automatic **client code generation** in many languages. + +### Automatic docs + +Interactive API documentation and exploration web user interfaces. As the framework is based on OpenAPI, there are multiple options, 2 included by default. + +* Swagger UI, with interactive exploration, call and test your API directly from the browser. ![Swagger UI interaction](img/index/index-03-swagger-02.png) @@ -14,7 +23,13 @@ ![ReDoc](img/index/index-06-redoc-02.png) -* All based on standard **Python 3.6 type** declarations (thanks to Pydantic). No new syntax to learn: +### Just Modern Python + +It's all based on standard **Python 3.6 type** declarations (thanks to Pydantic). No new syntax to learn. Just standard modern Python. + +If you need a 2 minute refresher of how to use Python types (even if you don't use FastAPI), check the tutorial section: [Python types](tutorial/python-types.md). + +You write standard Python with types: ```Python from typing import List, Dict @@ -55,39 +70,101 @@ second_user_data = { my_second_user: User = User(**second_user_data) ``` -* Sensible **defaults** for everything, with optional configurations everywhere. -* Validation for many **data types**, including: +### Editor support + +All the framework was designed to be easy and intuitive to use, all the decisons where tested on multiple editors even before starting development, to ensure the best development experience. + +In the last Python developer survey it was clear that the most used feature is "autocompletion". + +The whole **FastAPI** framework is based to satisfy that. Autocompletion works everywhere. + +You will rarely need to come back to the docs. + +Here's how your editor might help you: + +* in Visual Studio Code: + +![editor support](img/vscode-completion.png) + +* in PyCharm: + +![editor support](img/pycharm-completion.png) + +You will get completion in code you might even consider imposible before. As for example, the `price` key inside a JSON body (that could have been nested) that comes from a request. + +No more typing the wrong key names, coming back and forth between docs, or scrolling up and down to find if you finally used `username` or `user_name`. + +### Short + +It has sensible **defaults** for everything, with optional configurations everywhere. All the parameters can be fine-tuned to do what you need and to define the API you need. + +But by default, it all **"just works"**. + +### Validation + +* Validation for most (or all?) Python **data types**, including: * JSON objects (`dict`). * JSON array (`list`) defining item types. * String (`str`) fields, defining min and max lengths. * Numbers (`int`, `float`) with min and max values, etc. -* Security and authentication included: all the security schemes defined in OpenAPI, including: - * HTTP Basic. - * **OAuth2** (also with **JWT tokens**) - * API keys, etc. -* Plus the security features from Starlette (including session cookies). -* All built as reusable tools and components that are easy to integrate with your systems, data stores, databases, etc. -* Extremely easy, but extremely powerful Dependency Injection system: - * Even dependencies can have dependencies, creating a hierarchy or **"graph" of dependencies**. - * All **automatically handled** by the framework. - * All the dependencies can **augment the endpoint** parameters and constraints. - * **Automatic validation** even for parameters from dependencies. - * Support for complex user authentication systems, **database connections**, etc. -* **No compromise** with databases, frontends, etc. But easy integration with all. -* **Unlimited "plug-ins"**: - * Or in other way, no need for them, import and use the code you need. - * Any integration is designed to be so simple to use (with dependencies) that you can create a "plug-in" for your application in 2 lines of code using the same structure and syntax as for your endpoints. -* Fully compatible with (and based on) **Starlette**. - * Any additional Starlette code you have, will also work. -* Fully compatible with (and based on) **Pydantic**. - * Any additional Pydantic code you have will also work. - * Including external libraries also based on Pydantic, as ORMs, ODMs for databases. + +* Validation for more exotic types, like: + * URL. + * Email. + * UUID. + * ...and others. + +All the validation is handled by the well-established and robust **Pydantic**. + +### Security and authentication + +Security and authentication integrated. Without any compromise with databases or data models. + +All the security schemes defined in OpenAPI, including: + +* HTTP Basic. +* **OAuth2** (also with **JWT tokens**). Check the [tutorial on OAuth2 with JWT](tutorial/oauth2-jwt.md). +* API keys in: + * Headers. + * Query parameters. + * Cookies, etc. + +Plus all the security features from Starlette (including **session cookies**). + +All built as reusable tools and components that are easy to integrate with your systems, data stores, relational and NoSQL databases, etc. + +### Dependency Injection + +FastAPI includes an extremely easy to use, but extremely powerful Dependency Injection system. + +* Even dependencies can have dependencies, creating a hierarchy or **"graph" of dependencies**. +* All **automatically handled** by the framework. +* All the dependencies can require data from requests and **augment the endpoint** constraints and automatic documentation. +* **Automatic validation** even for endpoint parameters defined in dependencies. +* Support for complex user authentication systems, **database connections**, etc. +* **No compromise** with databases, frontends, etc. But easy integration with all of them. + + +### Unlimited "plug-ins" + +Or in other way, no need for them, import and use the code you need. + +Any integration is designed to be so simple to use (with dependencies) that you can create a "plug-in" for your application in 2 lines of code using the same structure and syntax used for your endpoints. + + +### Tested + * 100% test coverage (* not yet, in a couple days). * 100% type annotated code base. + ## Starlette features -Plus **Starlette**'s features (FastAPI is just Starlette on steroids): +**FastAPI** is fully compatible with (and based on) Starlette. So, any additional Starlette code you have, will also work. + +`FastAPI` is actually a sub-class of `Starlette`. So, if you already know or use Starlette, most of the functionality will work the same way. + +With **FastAPI** you get all of **Starlette**'s features (as FastAPI is just Starlette on steroids): * Seriously impressive performance. It is one of the fastest Python frameworks available, on par with **NodeJS** and **Go**. * **WebSocket** support. @@ -102,7 +179,15 @@ Plus **Starlette**'s features (FastAPI is just Starlette on steroids): ## Pydantic features -Plus **Pydantic**'s features: +**FastAPI** is fully compatible with (and based on) Pydantic. So, any additional Pydantic code you have, will also work. + +Including external libraries also based on Pydantic, as ORMs, ODMs for databases. + +This also means that in many cases you can pass the same object you get from a request **directly to the database**, as everything is validated automatically. + +The same applies the other way around, in many cases you can just pass the object you get from the database **directly to the client**. + +With **FastAPI** you get all of **Pydantic**'s features (as FastAPI is based on Pydantic for all the data handling): * **No brainfuck**: * No new schema definition micro-language to learn. diff --git a/docs/index.md b/docs/index.md index be9f910e0..3557be2a4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -26,9 +26,9 @@ FastAPI is a modern, fast (high-performance), web framework for building APIs wi The key features are: -* **Fast**: Very high performance, on par with **NodeJS** and **Go**. -* **Easy**: Designed to be easy to use and learn. -* **Intuitive**: Great editor support. Completion (auto-complete, IntelliSense) everywhere. +* **Fast**: Very high performance, on par with **NodeJS** and **Go** (thanks to Starlette and Pydantic). +* **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. * **Robust**: Get production-ready code. With automatic interactive documentation. * **Standards-based**: Based on (and fully compatible with) the open standards for APIs: OpenAPI and JSON Schema. diff --git a/docs/tutorial/oauth2-jwt.md b/docs/tutorial/oauth2-jwt.md new file mode 100644 index 000000000..39fe646c4 --- /dev/null +++ b/docs/tutorial/oauth2-jwt.md @@ -0,0 +1 @@ +Sorry! Coming soon... come back in a couple days. \ No newline at end of file diff --git a/docs/tutorial/python-types.md b/docs/tutorial/python-types.md new file mode 100644 index 000000000..39fe646c4 --- /dev/null +++ b/docs/tutorial/python-types.md @@ -0,0 +1 @@ +Sorry! Coming soon... come back in a couple days. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 9d8c94588..12e462528 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -15,8 +15,8 @@ edit_uri: "" nav: - Introduction: 'index.md' - - Tutorial: 'tutorial/index.md' - Features: 'features.md' + - Tutorial: 'tutorial/index.md' markdown_extensions: