:memo: Update docs, clarify what's a schema

diff --git a/README.md b/README.md
index a783067fe4fd5d29b4dc5bd5ccfa8b8ff761e0be..1c4b523411bd95d8300e8a37d56c43b058e60374 100644 (file)
--- a/README.md
+++ b/README.md
@@ -291,7 +291,7 @@ Coming back to the previous code example, **FastAPI** will:
     * 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 as an OpenAPI schema, that can be used by:
+* Document everything with OpenAPI, that can be used by:
     * Interactive documentation sytems.
     * Automatic client code generation systems, for many languages.
 * Provide 2 interactive documentation web interfaces directly.

diff --git a/docs/index.md b/docs/index.md
index a783067fe4fd5d29b4dc5bd5ccfa8b8ff761e0be..1c4b523411bd95d8300e8a37d56c43b058e60374 100644 (file)
--- a/docs/index.md
+++ b/docs/index.md
@@ -291,7 +291,7 @@ Coming back to the previous code example, **FastAPI** will:
     * 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 as an OpenAPI schema, that can be used by:
+* Document everything with OpenAPI, that can be used by:
     * Interactive documentation sytems.
     * Automatic client code generation systems, for many languages.
 * Provide 2 interactive documentation web interfaces directly.

diff --git a/docs/tutorial/first-steps.md b/docs/tutorial/first-steps.md
index 5b41bfc4a9156d9d5f59427a66df9abedcddcf03..cf0809692806fb05b60a095fcfae1ced28d3c0a9 100644 (file)
--- a/docs/tutorial/first-steps.md
+++ b/docs/tutorial/first-steps.md
@@ -57,6 +57,32 @@ You will see the alternative automatic documentation (provided by <a href="https
 
 ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png)
 
+### OpenAPI
+
+**FastAPI** generates a "schema" with all your API using the **OpenAPI** standard for defining APIs.
+
+#### "Schema"
+
+A "schema" is a definition or description of something. Not the code that implements it, but just the abstract description.
+
+#### API "schema"
+
+In this case, OpenAPI is a specification that dictates how to define a schema of your API.
+
+This OpenAPI schema would include your API paths, the posible parameters they take, etc.
+
+#### Data "schema"
+
+The term "schema" might also refer to the shape of some data, like a JSON content.
+
+In that case, it would mean the JSON attributes, and data types they have, etc.
+
+#### OpenAPI and JSON Schema
+
+OpenAPI defines an API schema for your API. And that schema includes definitions (or "schemas") of the data sent and received by your API using **JSON Schema**, the standard for JSON data schemas.
+
+#### Check it
+
 If you are curious about how the raw OpenAPI schema looks like, it is just an automatically generated JSON with the descriptions of all your API.
 
 You can see it directly at: <a href="http://127.0.0.1:8000/openapi.json" target="_blank">http://127.0.0.1:8000/openapi.json</a>.
@@ -84,6 +110,14 @@ It will show a JSON starting with something like:
 ...
 ```
 
+#### What for?
+
+This OpenAPI schema is what powers the 2 interactive documentation systems included.
+
+And there are dozens of alternatives, all based on OpenAPI. You could easily add any of those alternatives to your application built with **FastAPI**.
+
+You could also use it to generate code automatically, for clients that communicate with your API. For example, frontend, mobile or IoT applications.
+
 ## Recap, step by step
 
 ### Step 1: import `FastAPI`