forked from fastapi/fastapi
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
📝 Update GraphQL docs, recommend Strawberry (fastapi#3981)
- Loading branch information
Showing
8 changed files
with
56 additions
and
39 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,44 +1,56 @@ | ||
| # GraphQL | ||
|
|
||
| **FastAPI** has optional support for GraphQL (provided by Starlette directly), using the `graphene` library. | ||
| As **FastAPI** is based on the **ASGI** standard, it's very easy to integrate any **GraphQL** library also compatible with ASGI. | ||
|
|
||
| You can combine normal FastAPI *path operations* with GraphQL on the same application. | ||
|
|
||
| ## Import and use `graphene` | ||
| !!! tip | ||
| **GraphQL** solves some very specific use cases. | ||
|
|
||
| GraphQL is implemented with Graphene, you can check <a href="https://docs.graphene-python.org/en/latest/quickstart/" class="external-link" target="_blank">Graphene's docs</a> for more details. | ||
| It has **advantages** and **disadvantages** when compared to common **web APIs**. | ||
|
|
||
| Import `graphene` and define your GraphQL data: | ||
| Make sure you evaluate if the **benefits** for your use case compensate the **drawbacks**. 🤓 | ||
|
|
||
| ```Python hl_lines="1 6-10" | ||
| {!../../../docs_src/graphql/tutorial001.py!} | ||
| ``` | ||
| ## GraphQL Libraries | ||
|
|
||
| Here are some of the **GraphQL** libraries that have **ASGI** support. You could use them with **FastAPI**: | ||
|
|
||
| * <a href="https://strawberry.rocks/" class="external-link" target="_blank">Strawberry</a> 🍓 | ||
| * With <a href="https://strawberry.rocks/docs/integrations/fastapi" class="external-link" target="_blank">docs for FastAPI</a> | ||
| * <a href="https://ariadnegraphql.org/" class="external-link" target="_blank">Ariadne</a> | ||
| * With <a href="https://ariadnegraphql.org/docs/starlette-integration" class="external-link" target="_blank">docs for Starlette</a> (that also apply to FastAPI) | ||
| * <a href="https://tartiflette.io/" class="external-link" target="_blank">Tartiflette</a> | ||
| * With <a href="https://tartiflette.github.io/tartiflette-asgi/" class="external-link" target="_blank">Tartiflette ASGI</a> to provide ASGI integration | ||
| * <a href="https://graphene-python.org/" class="external-link" target="_blank">Graphene</a> | ||
| * With <a href="https://github.com/ciscorn/starlette-graphene3" class="external-link" target="_blank">starlette-graphene3</a> | ||
|
|
||
| ## GraphQL with Strawberry | ||
|
|
||
| If you need or want to work with **GraphQL**, <a href="https://strawberry.rocks/" class="external-link" target="_blank">**Strawberry**</a> is the **recommended** library as it has the design closest to **FastAPI's** design, it's all based on **type annotations**. | ||
|
|
||
| ## Add Starlette's `GraphQLApp` | ||
| Depending on your use case, you might prefer to use a different library, but if you asked me, I would probably suggest you try **Strawberry**. | ||
|
|
||
| Then import and add Starlette's `GraphQLApp`: | ||
| Here's a small preview of how you could integrate Strawberry with FastAPI: | ||
|
|
||
| ```Python hl_lines="3 14" | ||
| ```Python hl_lines="3 22 25-26" | ||
| {!../../../docs_src/graphql/tutorial001.py!} | ||
| ``` | ||
|
|
||
| !!! info | ||
| Here we are using `.add_route`, that is the way to add a route in Starlette (inherited by FastAPI) without declaring the specific operation (as would be with `.get()`, `.post()`, etc). | ||
| You can learn more about Strawberry in the <a href="https://strawberry.rocks/" class="external-link" target="_blank">Strawberry documentation</a>. | ||
|
|
||
| ## Check it | ||
| And also the docs about <a href="https://strawberry.rocks/docs/integrations/fastapi" class="external-link" target="_blank">Strawberry with FastAPI</a>. | ||
|
|
||
| Run it with Uvicorn and open your browser at <a href="http://127.0.0.1:8000" class="external-link" target="_blank">http://127.0.0.1:8000</a>. | ||
| ## Older `GraphQLApp` from Starlette | ||
|
|
||
| You will see GraphiQL web user interface: | ||
| Previous versions of Starlette included a `GraphQLApp` class to integrate with <a href="https://graphene-python.org/" class="external-link" target="_blank">Graphene</a>. | ||
|
|
||
| <img src="/img/tutorial/graphql/image01.png"> | ||
| It was deprecated from Starlette, but if you have code that used it, you can easily **migrate** to <a href="https://github.com/ciscorn/starlette-graphene3" class="external-link" target="_blank">starlette-graphene3</a>, that covers the same use case and has an **almost identical interface**. | ||
|
|
||
| ## More details | ||
| !!! tip | ||
| If you need GraphQL, I still would recommend you check out <a href="https://strawberry.rocks/" class="external-link" target="_blank">Strawberry</a>, as it's based on type annotations instead of custom classes and types. | ||
|
|
||
| For more details, including: | ||
| ## Learn More | ||
|
|
||
| * Accessing request information | ||
| * Adding background tasks | ||
| * Using normal or async functions | ||
| You can learn more about **GraphQL** in the <a href="https://graphql.org/" class="external-link" target="_blank">official GraphQL documentation</a>. | ||
|
|
||
| check the official <a href="https://www.starlette.io/graphql/" class="external-link" target="_blank">Starlette GraphQL docs</a>. | ||
| You can also read more about each those libraries described above in their links. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,14 +1,26 @@ | ||
| import graphene | ||
| import strawberry | ||
| from fastapi import FastAPI | ||
| from starlette.graphql import GraphQLApp | ||
| from strawberry.asgi import GraphQL | ||
|
|
||
|
|
||
| class Query(graphene.ObjectType): | ||
| hello = graphene.String(name=graphene.String(default_value="stranger")) | ||
| @strawberry.type | ||
| class User: | ||
| name: str | ||
| age: int | ||
|
|
||
| def resolve_hello(self, info, name): | ||
| return "Hello " + name | ||
|
|
||
| @strawberry.type | ||
| class Query: | ||
| @strawberry.field | ||
| def user(self) -> User: | ||
| return User(name="Patrick", age=100) | ||
|
|
||
|
|
||
| schema = strawberry.Schema(query=Query) | ||
|
|
||
|
|
||
| graphql_app = GraphQL(schema) | ||
|
|
||
| app = FastAPI() | ||
| app.add_route("/", GraphQLApp(schema=graphene.Schema(query=Query))) | ||
| app.add_route("/graphql", graphql_app) | ||
| app.add_websocket_route("/graphql", graphql_app) |