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.
@@ -14,7 +23,13 @@
-* 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:
+
+
+
+* in PyCharm:
+
+
+
+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: