Peter Volf
10 months ago
committed by
GitHub
GitHub
249 changed files with 3162 additions and 2319 deletions
@ -0,0 +1,45 @@ |
|||
labels: [lang-all] |
|||
body: |
|||
- type: markdown |
|||
attributes: |
|||
value: | |
|||
Thanks for your interest in helping translate the FastAPI docs! 🌍 |
|||
|
|||
Please follow these instructions carefully to propose a new language translation. 🙏 |
|||
|
|||
This structured process helps ensure translations can be properly maintained long-term. |
|||
- type: checkboxes |
|||
id: checks |
|||
attributes: |
|||
label: Initial Checks |
|||
description: Please confirm and check all the following options. |
|||
options: |
|||
- label: I checked that this language is not already being translated in FastAPI docs. |
|||
required: true |
|||
- label: I searched existing discussions to ensure no one else proposed this language. |
|||
required: true |
|||
- label: I am a native speaker of the language I want to help translate. |
|||
required: true |
|||
- type: input |
|||
id: language |
|||
attributes: |
|||
label: Target Language |
|||
description: What language do you want to translate the FastAPI docs into? |
|||
placeholder: e.g. Latin |
|||
validations: |
|||
required: true |
|||
- type: textarea |
|||
id: additional_info |
|||
attributes: |
|||
label: Additional Information |
|||
description: Any other relevant information about your translation proposal |
|||
- type: markdown |
|||
attributes: |
|||
value: | |
|||
Translations are automatized with AI and then reviewed by native speakers. 🤖 🙋 |
|||
|
|||
This allows us to keep them consistent and up-to-date. |
|||
|
|||
If there are several native speakers commenting on this discussion and |
|||
committing to help review new translations, the FastAPI team will review it |
|||
and potentially make it an official translation. 😎 |
|||
@ -0,0 +1,19 @@ |
|||
name: "Conflict detector" |
|||
on: |
|||
push: |
|||
pull_request_target: |
|||
types: [synchronize] |
|||
|
|||
jobs: |
|||
main: |
|||
permissions: |
|||
contents: read |
|||
pull-requests: write |
|||
runs-on: ubuntu-latest |
|||
steps: |
|||
- name: Check if PRs have merge conflicts |
|||
uses: eps1lon/actions-label-merge-conflict@v3 |
|||
with: |
|||
dirtyLabel: "conflicts" |
|||
repoToken: "${{ secrets.GITHUB_TOKEN }}" |
|||
commentOnDirty: "This pull request has a merge conflict that needs to be resolved." |
|||
@ -20,9 +20,9 @@ jobs: |
|||
env: |
|||
GITHUB_CONTEXT: ${{ toJson(github) }} |
|||
run: echo "$GITHUB_CONTEXT" |
|||
- uses: actions/checkout@v4 |
|||
- uses: actions/checkout@v5 |
|||
- name: Set up Python |
|||
uses: actions/setup-python@v5 |
|||
uses: actions/setup-python@v6 |
|||
with: |
|||
python-version: "3.10" |
|||
# Issue ref: https://github.com/actions/setup-python/issues/436 |
|||
@ -35,7 +35,7 @@ jobs: |
|||
TIANGOLO_BUILD_PACKAGE: ${{ matrix.package }} |
|||
run: python -m build |
|||
- name: Publish |
|||
uses: pypa/[email protected]2.4 |
|||
uses: pypa/[email protected]3.0 |
|||
- name: Dump GitHub context |
|||
env: |
|||
GITHUB_CONTEXT: ${{ toJson(github) }} |
|||
|
|||
@ -0,0 +1,77 @@ |
|||
name: Translate |
|||
|
|||
on: |
|||
workflow_dispatch: |
|||
inputs: |
|||
debug_enabled: |
|||
description: Run with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate) |
|||
required: false |
|||
default: "false" |
|||
command: |
|||
description: Command to run |
|||
type: choice |
|||
options: |
|||
- translate-page |
|||
- translate-lang |
|||
- update-outdated |
|||
- add-missing |
|||
- update-and-add |
|||
- remove-all-removable |
|||
language: |
|||
description: Language to translate to as a letter code (e.g. "es" for Spanish) |
|||
type: string |
|||
required: false |
|||
default: "" |
|||
en_path: |
|||
description: File path in English to translate (e.g. docs/en/docs/index.md) |
|||
type: string |
|||
required: false |
|||
default: "" |
|||
|
|||
env: |
|||
UV_SYSTEM_PYTHON: 1 |
|||
|
|||
jobs: |
|||
job: |
|||
if: github.repository_owner == 'fastapi' |
|||
runs-on: ubuntu-latest |
|||
permissions: |
|||
contents: write |
|||
steps: |
|||
- name: Dump GitHub context |
|||
env: |
|||
GITHUB_CONTEXT: ${{ toJson(github) }} |
|||
run: echo "$GITHUB_CONTEXT" |
|||
- uses: actions/checkout@v5 |
|||
- name: Set up Python |
|||
uses: actions/setup-python@v6 |
|||
with: |
|||
python-version: "3.11" |
|||
- name: Setup uv |
|||
uses: astral-sh/setup-uv@v6 |
|||
with: |
|||
version: "0.4.15" |
|||
enable-cache: true |
|||
cache-dependency-glob: | |
|||
requirements**.txt |
|||
pyproject.toml |
|||
- name: Install Dependencies |
|||
run: uv pip install -r requirements-github-actions.txt -r requirements-translations.txt |
|||
# Allow debugging with tmate |
|||
- name: Setup tmate session |
|||
uses: mxschmitt/action-tmate@v3 |
|||
if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.debug_enabled == 'true' }} |
|||
with: |
|||
limit-access-to-actor: true |
|||
env: |
|||
GITHUB_TOKEN: ${{ secrets.FASTAPI_TRANSLATIONS }} |
|||
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} |
|||
- name: FastAPI Translate |
|||
run: | |
|||
python ./scripts/translate.py ${{ github.event.inputs.command }} |
|||
python ./scripts/translate.py make-pr |
|||
env: |
|||
GITHUB_TOKEN: ${{ secrets.FASTAPI_TRANSLATIONS }} |
|||
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} |
|||
LANGUAGE: ${{ github.event.inputs.language }} |
|||
EN_PATH: ${{ github.event.inputs.en_path }} |
|||
@ -16,7 +16,7 @@ You can learn more about [FastAPI versions and how to pin and upgrade them](http |
|||
|
|||
If you think you found a vulnerability, and even if you are not sure about it, please report it right away by sending an email to: [email protected]. Please try to be as explicit as possible, describing all the steps and example code to reproduce the security issue. |
|||
|
|||
I (the author, [@tiangolo](https://twitter.com/tiangolo)) will review it thoroughly and get back to you. |
|||
I (the author, [@tiangolo](https://x.com/tiangolo)) will review it thoroughly and get back to you. |
|||
|
|||
## Public Discussions |
|||
|
|||
|
|||
@ -1,495 +1,495 @@ |
|||
- name: full-stack-fastapi-template |
|||
html_url: https://github.com/fastapi/full-stack-fastapi-template |
|||
stars: 34156 |
|||
stars: 37341 |
|||
owner_login: fastapi |
|||
owner_html_url: https://github.com/fastapi |
|||
- name: Hello-Python |
|||
html_url: https://github.com/mouredev/Hello-Python |
|||
stars: 30835 |
|||
stars: 31799 |
|||
owner_login: mouredev |
|||
owner_html_url: https://github.com/mouredev |
|||
- name: serve |
|||
html_url: https://github.com/jina-ai/serve |
|||
stars: 21631 |
|||
stars: 21721 |
|||
owner_login: jina-ai |
|||
owner_html_url: https://github.com/jina-ai |
|||
- name: HivisionIDPhotos |
|||
html_url: https://github.com/Zeyi-Lin/HivisionIDPhotos |
|||
stars: 18125 |
|||
stars: 19114 |
|||
owner_login: Zeyi-Lin |
|||
owner_html_url: https://github.com/Zeyi-Lin |
|||
- name: sqlmodel |
|||
html_url: https://github.com/fastapi/sqlmodel |
|||
stars: 16249 |
|||
stars: 16678 |
|||
owner_login: fastapi |
|||
owner_html_url: https://github.com/fastapi |
|||
- name: Douyin_TikTok_Download_API |
|||
html_url: https://github.com/Evil0ctal/Douyin_TikTok_Download_API |
|||
stars: 13279 |
|||
stars: 14126 |
|||
owner_login: Evil0ctal |
|||
owner_html_url: https://github.com/Evil0ctal |
|||
- name: fastapi-best-practices |
|||
html_url: https://github.com/zhanymkanov/fastapi-best-practices |
|||
stars: 12334 |
|||
stars: 13189 |
|||
owner_login: zhanymkanov |
|||
owner_html_url: https://github.com/zhanymkanov |
|||
- name: awesome-fastapi |
|||
html_url: https://github.com/mjhea0/awesome-fastapi |
|||
stars: 9934 |
|||
stars: 10264 |
|||
owner_login: mjhea0 |
|||
owner_html_url: https://github.com/mjhea0 |
|||
- name: fastapi_mcp |
|||
html_url: https://github.com/tadata-org/fastapi_mcp |
|||
stars: 9964 |
|||
owner_login: tadata-org |
|||
owner_html_url: https://github.com/tadata-org |
|||
- name: FastUI |
|||
html_url: https://github.com/pydantic/FastUI |
|||
stars: 8838 |
|||
stars: 8861 |
|||
owner_login: pydantic |
|||
owner_html_url: https://github.com/pydantic |
|||
- name: XHS-Downloader |
|||
html_url: https://github.com/JoeanAmier/XHS-Downloader |
|||
stars: 7962 |
|||
stars: 8576 |
|||
owner_login: JoeanAmier |
|||
owner_html_url: https://github.com/JoeanAmier |
|||
- name: nonebot2 |
|||
html_url: https://github.com/nonebot/nonebot2 |
|||
stars: 6834 |
|||
owner_login: nonebot |
|||
owner_html_url: https://github.com/nonebot |
|||
- name: SurfSense |
|||
html_url: https://github.com/MODSetter/SurfSense |
|||
stars: 7421 |
|||
owner_login: MODSetter |
|||
owner_html_url: https://github.com/MODSetter |
|||
- name: FileCodeBox |
|||
html_url: https://github.com/vastsa/FileCodeBox |
|||
stars: 6783 |
|||
stars: 7179 |
|||
owner_login: vastsa |
|||
owner_html_url: https://github.com/vastsa |
|||
- name: fastapi_mcp |
|||
html_url: https://github.com/tadata-org/fastapi_mcp |
|||
stars: 5846 |
|||
owner_login: tadata-org |
|||
owner_html_url: https://github.com/tadata-org |
|||
- name: polar |
|||
html_url: https://github.com/polarsource/polar |
|||
stars: 7106 |
|||
owner_login: polarsource |
|||
owner_html_url: https://github.com/polarsource |
|||
- name: nonebot2 |
|||
html_url: https://github.com/nonebot/nonebot2 |
|||
stars: 6998 |
|||
owner_login: nonebot |
|||
owner_html_url: https://github.com/nonebot |
|||
- name: hatchet |
|||
html_url: https://github.com/hatchet-dev/hatchet |
|||
stars: 5773 |
|||
stars: 5978 |
|||
owner_login: hatchet-dev |
|||
owner_html_url: https://github.com/hatchet-dev |
|||
- name: serge |
|||
html_url: https://github.com/serge-chat/serge |
|||
stars: 5728 |
|||
stars: 5751 |
|||
owner_login: serge-chat |
|||
owner_html_url: https://github.com/serge-chat |
|||
- name: polar |
|||
html_url: https://github.com/polarsource/polar |
|||
stars: 5709 |
|||
owner_login: polarsource |
|||
owner_html_url: https://github.com/polarsource |
|||
- name: fastapi-users |
|||
html_url: https://github.com/fastapi-users/fastapi-users |
|||
stars: 5336 |
|||
stars: 5517 |
|||
owner_login: fastapi-users |
|||
owner_html_url: https://github.com/fastapi-users |
|||
- name: strawberry |
|||
html_url: https://github.com/strawberry-graphql/strawberry |
|||
stars: 4317 |
|||
stars: 4392 |
|||
owner_login: strawberry-graphql |
|||
owner_html_url: https://github.com/strawberry-graphql |
|||
- name: chatgpt-web-share |
|||
html_url: https://github.com/chatpire/chatgpt-web-share |
|||
stars: 4301 |
|||
stars: 4305 |
|||
owner_login: chatpire |
|||
owner_html_url: https://github.com/chatpire |
|||
- name: atrilabs-engine |
|||
html_url: https://github.com/Atri-Labs/atrilabs-engine |
|||
stars: 4106 |
|||
owner_login: Atri-Labs |
|||
owner_html_url: https://github.com/Atri-Labs |
|||
- name: dynaconf |
|||
html_url: https://github.com/dynaconf/dynaconf |
|||
stars: 4045 |
|||
owner_login: dynaconf |
|||
owner_html_url: https://github.com/dynaconf |
|||
- name: poem |
|||
html_url: https://github.com/poem-web/poem |
|||
stars: 4037 |
|||
stars: 4157 |
|||
owner_login: poem-web |
|||
owner_html_url: https://github.com/poem-web |
|||
- name: farfalle |
|||
html_url: https://github.com/rashadphz/farfalle |
|||
stars: 3348 |
|||
owner_login: rashadphz |
|||
owner_html_url: https://github.com/rashadphz |
|||
- name: dynaconf |
|||
html_url: https://github.com/dynaconf/dynaconf |
|||
stars: 4112 |
|||
owner_login: dynaconf |
|||
owner_html_url: https://github.com/dynaconf |
|||
- name: atrilabs-engine |
|||
html_url: https://github.com/Atri-Labs/atrilabs-engine |
|||
stars: 4104 |
|||
owner_login: Atri-Labs |
|||
owner_html_url: https://github.com/Atri-Labs |
|||
- name: Kokoro-FastAPI |
|||
html_url: https://github.com/remsky/Kokoro-FastAPI |
|||
stars: 3569 |
|||
owner_login: remsky |
|||
owner_html_url: https://github.com/remsky |
|||
- name: LitServe |
|||
html_url: https://github.com/Lightning-AI/LitServe |
|||
stars: 3347 |
|||
stars: 3531 |
|||
owner_login: Lightning-AI |
|||
owner_html_url: https://github.com/Lightning-AI |
|||
- name: fastapi-admin |
|||
html_url: https://github.com/fastapi-admin/fastapi-admin |
|||
stars: 3309 |
|||
owner_login: fastapi-admin |
|||
owner_html_url: https://github.com/fastapi-admin |
|||
- name: datamodel-code-generator |
|||
html_url: https://github.com/koxudaxi/datamodel-code-generator |
|||
stars: 3291 |
|||
owner_login: koxudaxi |
|||
owner_html_url: https://github.com/koxudaxi |
|||
- name: logfire |
|||
html_url: https://github.com/pydantic/logfire |
|||
stars: 3288 |
|||
stars: 3510 |
|||
owner_login: pydantic |
|||
owner_html_url: https://github.com/pydantic |
|||
- name: datamodel-code-generator |
|||
html_url: https://github.com/koxudaxi/datamodel-code-generator |
|||
stars: 3425 |
|||
owner_login: koxudaxi |
|||
owner_html_url: https://github.com/koxudaxi |
|||
- name: farfalle |
|||
html_url: https://github.com/rashadphz/farfalle |
|||
stars: 3420 |
|||
owner_login: rashadphz |
|||
owner_html_url: https://github.com/rashadphz |
|||
- name: fastapi-admin |
|||
html_url: https://github.com/fastapi-admin/fastapi-admin |
|||
stars: 3417 |
|||
owner_login: fastapi-admin |
|||
owner_html_url: https://github.com/fastapi-admin |
|||
- name: huma |
|||
html_url: https://github.com/danielgtaylor/huma |
|||
stars: 3201 |
|||
stars: 3351 |
|||
owner_login: danielgtaylor |
|||
owner_html_url: https://github.com/danielgtaylor |
|||
- name: tracecat |
|||
html_url: https://github.com/TracecatHQ/tracecat |
|||
stars: 3213 |
|||
owner_login: TracecatHQ |
|||
owner_html_url: https://github.com/TracecatHQ |
|||
- name: opyrator |
|||
html_url: https://github.com/ml-tooling/opyrator |
|||
stars: 3132 |
|||
stars: 3131 |
|||
owner_login: ml-tooling |
|||
owner_html_url: https://github.com/ml-tooling |
|||
- name: Kokoro-FastAPI |
|||
html_url: https://github.com/remsky/Kokoro-FastAPI |
|||
stars: 3099 |
|||
owner_login: remsky |
|||
owner_html_url: https://github.com/remsky |
|||
- name: docarray |
|||
html_url: https://github.com/docarray/docarray |
|||
stars: 3075 |
|||
stars: 3098 |
|||
owner_login: docarray |
|||
owner_html_url: https://github.com/docarray |
|||
- name: fastapi-realworld-example-app |
|||
html_url: https://github.com/nsidnev/fastapi-realworld-example-app |
|||
stars: 2902 |
|||
stars: 2925 |
|||
owner_login: nsidnev |
|||
owner_html_url: https://github.com/nsidnev |
|||
- name: tracecat |
|||
html_url: https://github.com/TracecatHQ/tracecat |
|||
stars: 2888 |
|||
owner_login: TracecatHQ |
|||
owner_html_url: https://github.com/TracecatHQ |
|||
- name: uvicorn-gunicorn-fastapi-docker |
|||
html_url: https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker |
|||
stars: 2775 |
|||
stars: 2796 |
|||
owner_login: tiangolo |
|||
owner_html_url: https://github.com/tiangolo |
|||
- name: best-of-web-python |
|||
html_url: https://github.com/ml-tooling/best-of-web-python |
|||
stars: 2537 |
|||
stars: 2583 |
|||
owner_login: ml-tooling |
|||
owner_html_url: https://github.com/ml-tooling |
|||
- name: RasaGPT |
|||
html_url: https://github.com/paulpierre/RasaGPT |
|||
stars: 2427 |
|||
stars: 2438 |
|||
owner_login: paulpierre |
|||
owner_html_url: https://github.com/paulpierre |
|||
- name: fastapi-react |
|||
html_url: https://github.com/Buuntu/fastapi-react |
|||
stars: 2397 |
|||
stars: 2432 |
|||
owner_login: Buuntu |
|||
owner_html_url: https://github.com/Buuntu |
|||
- name: FastAPI-template |
|||
html_url: https://github.com/s3rius/FastAPI-template |
|||
stars: 2334 |
|||
stars: 2388 |
|||
owner_login: s3rius |
|||
owner_html_url: https://github.com/s3rius |
|||
- name: nextpy |
|||
html_url: https://github.com/dot-agent/nextpy |
|||
stars: 2295 |
|||
owner_login: dot-agent |
|||
owner_html_url: https://github.com/dot-agent |
|||
- name: sqladmin |
|||
html_url: https://github.com/aminalaee/sqladmin |
|||
stars: 2235 |
|||
stars: 2323 |
|||
owner_login: aminalaee |
|||
owner_html_url: https://github.com/aminalaee |
|||
- name: nextpy |
|||
html_url: https://github.com/dot-agent/nextpy |
|||
stars: 2314 |
|||
owner_login: dot-agent |
|||
owner_html_url: https://github.com/dot-agent |
|||
- name: mcp-context-forge |
|||
html_url: https://github.com/IBM/mcp-context-forge |
|||
stars: 2236 |
|||
owner_login: IBM |
|||
owner_html_url: https://github.com/IBM |
|||
- name: 30-Days-of-Python |
|||
html_url: https://github.com/codingforentrepreneurs/30-Days-of-Python |
|||
stars: 2181 |
|||
stars: 2196 |
|||
owner_login: codingforentrepreneurs |
|||
owner_html_url: https://github.com/codingforentrepreneurs |
|||
- name: supabase-py |
|||
html_url: https://github.com/supabase/supabase-py |
|||
stars: 2194 |
|||
owner_login: supabase |
|||
owner_html_url: https://github.com/supabase |
|||
- name: langserve |
|||
html_url: https://github.com/langchain-ai/langserve |
|||
stars: 2119 |
|||
stars: 2157 |
|||
owner_login: langchain-ai |
|||
owner_html_url: https://github.com/langchain-ai |
|||
- name: fastapi-utils |
|||
html_url: https://github.com/fastapiutils/fastapi-utils |
|||
stars: 2100 |
|||
stars: 2155 |
|||
owner_login: fastapiutils |
|||
owner_html_url: https://github.com/fastapiutils |
|||
- name: supabase-py |
|||
html_url: https://github.com/supabase/supabase-py |
|||
stars: 2084 |
|||
owner_login: supabase |
|||
owner_html_url: https://github.com/supabase |
|||
- name: solara |
|||
html_url: https://github.com/widgetti/solara |
|||
stars: 2056 |
|||
stars: 2083 |
|||
owner_login: widgetti |
|||
owner_html_url: https://github.com/widgetti |
|||
- name: mangum |
|||
html_url: https://github.com/Kludex/mangum |
|||
stars: 1923 |
|||
stars: 1969 |
|||
owner_login: Kludex |
|||
owner_html_url: https://github.com/Kludex |
|||
- name: Yuxi-Know |
|||
html_url: https://github.com/xerrors/Yuxi-Know |
|||
stars: 1849 |
|||
owner_login: xerrors |
|||
owner_html_url: https://github.com/xerrors |
|||
- name: python-week-2022 |
|||
html_url: https://github.com/rochacbruno/python-week-2022 |
|||
stars: 1821 |
|||
stars: 1817 |
|||
owner_login: rochacbruno |
|||
owner_html_url: https://github.com/rochacbruno |
|||
- name: agentkit |
|||
html_url: https://github.com/BCG-X-Official/agentkit |
|||
stars: 1765 |
|||
stars: 1779 |
|||
owner_login: BCG-X-Official |
|||
owner_html_url: https://github.com/BCG-X-Official |
|||
- name: manage-fastapi |
|||
html_url: https://github.com/ycd/manage-fastapi |
|||
stars: 1756 |
|||
stars: 1770 |
|||
owner_login: ycd |
|||
owner_html_url: https://github.com/ycd |
|||
- name: ormar |
|||
html_url: https://github.com/collerek/ormar |
|||
stars: 1755 |
|||
stars: 1766 |
|||
owner_login: collerek |
|||
owner_html_url: https://github.com/collerek |
|||
- name: langchain-serve |
|||
html_url: https://github.com/jina-ai/langchain-serve |
|||
stars: 1631 |
|||
owner_login: jina-ai |
|||
owner_html_url: https://github.com/jina-ai |
|||
- name: piccolo |
|||
html_url: https://github.com/piccolo-orm/piccolo |
|||
stars: 1629 |
|||
stars: 1673 |
|||
owner_login: piccolo-orm |
|||
owner_html_url: https://github.com/piccolo-orm |
|||
- name: termpair |
|||
html_url: https://github.com/cs01/termpair |
|||
stars: 1616 |
|||
owner_login: cs01 |
|||
owner_html_url: https://github.com/cs01 |
|||
- name: openapi-python-client |
|||
html_url: https://github.com/openapi-generators/openapi-python-client |
|||
stars: 1603 |
|||
stars: 1667 |
|||
owner_login: openapi-generators |
|||
owner_html_url: https://github.com/openapi-generators |
|||
- name: langchain-serve |
|||
html_url: https://github.com/jina-ai/langchain-serve |
|||
stars: 1632 |
|||
owner_login: jina-ai |
|||
owner_html_url: https://github.com/jina-ai |
|||
- name: fastapi-cache |
|||
html_url: https://github.com/long2ice/fastapi-cache |
|||
stars: 1589 |
|||
stars: 1628 |
|||
owner_login: long2ice |
|||
owner_html_url: https://github.com/long2ice |
|||
- name: coronavirus-tracker-api |
|||
html_url: https://github.com/ExpDev07/coronavirus-tracker-api |
|||
stars: 1580 |
|||
owner_login: ExpDev07 |
|||
owner_html_url: https://github.com/ExpDev07 |
|||
- name: termpair |
|||
html_url: https://github.com/cs01/termpair |
|||
stars: 1622 |
|||
owner_login: cs01 |
|||
owner_html_url: https://github.com/cs01 |
|||
- name: vue-fastapi-admin |
|||
html_url: https://github.com/mizhexiaoxiao/vue-fastapi-admin |
|||
stars: 1591 |
|||
owner_login: mizhexiaoxiao |
|||
owner_html_url: https://github.com/mizhexiaoxiao |
|||
- name: slowapi |
|||
html_url: https://github.com/laurentS/slowapi |
|||
stars: 1533 |
|||
stars: 1580 |
|||
owner_login: laurentS |
|||
owner_html_url: https://github.com/laurentS |
|||
- name: coronavirus-tracker-api |
|||
html_url: https://github.com/ExpDev07/coronavirus-tracker-api |
|||
stars: 1578 |
|||
owner_login: ExpDev07 |
|||
owner_html_url: https://github.com/ExpDev07 |
|||
- name: fastapi-crudrouter |
|||
html_url: https://github.com/awtkns/fastapi-crudrouter |
|||
stars: 1518 |
|||
stars: 1531 |
|||
owner_login: awtkns |
|||
owner_html_url: https://github.com/awtkns |
|||
- name: awesome-fastapi-projects |
|||
html_url: https://github.com/Kludex/awesome-fastapi-projects |
|||
stars: 1461 |
|||
stars: 1473 |
|||
owner_login: Kludex |
|||
owner_html_url: https://github.com/Kludex |
|||
- name: vue-fastapi-admin |
|||
html_url: https://github.com/mizhexiaoxiao/vue-fastapi-admin |
|||
stars: 1409 |
|||
owner_login: mizhexiaoxiao |
|||
owner_html_url: https://github.com/mizhexiaoxiao |
|||
- name: awesome-python-resources |
|||
html_url: https://github.com/DjangoEx/awesome-python-resources |
|||
stars: 1393 |
|||
owner_login: DjangoEx |
|||
owner_html_url: https://github.com/DjangoEx |
|||
- name: FastAPI-boilerplate |
|||
html_url: https://github.com/benavlabs/FastAPI-boilerplate |
|||
stars: 1432 |
|||
owner_login: benavlabs |
|||
owner_html_url: https://github.com/benavlabs |
|||
- name: fastapi-pagination |
|||
html_url: https://github.com/uriyyo/fastapi-pagination |
|||
stars: 1378 |
|||
stars: 1428 |
|||
owner_login: uriyyo |
|||
owner_html_url: https://github.com/uriyyo |
|||
- name: awesome-python-resources |
|||
html_url: https://github.com/DjangoEx/awesome-python-resources |
|||
stars: 1413 |
|||
owner_login: DjangoEx |
|||
owner_html_url: https://github.com/DjangoEx |
|||
- name: bracket |
|||
html_url: https://github.com/evroon/bracket |
|||
stars: 1393 |
|||
owner_login: evroon |
|||
owner_html_url: https://github.com/evroon |
|||
- name: fastapi-boilerplate |
|||
html_url: https://github.com/teamhide/fastapi-boilerplate |
|||
stars: 1348 |
|||
stars: 1385 |
|||
owner_login: teamhide |
|||
owner_html_url: https://github.com/teamhide |
|||
- name: budgetml |
|||
html_url: https://github.com/ebhy/budgetml |
|||
stars: 1344 |
|||
stars: 1345 |
|||
owner_login: ebhy |
|||
owner_html_url: https://github.com/ebhy |
|||
- name: fastapi-amis-admin |
|||
html_url: https://github.com/amisadmin/fastapi-amis-admin |
|||
stars: 1284 |
|||
stars: 1327 |
|||
owner_login: amisadmin |
|||
owner_html_url: https://github.com/amisadmin |
|||
- name: bracket |
|||
html_url: https://github.com/evroon/bracket |
|||
stars: 1274 |
|||
owner_login: evroon |
|||
owner_html_url: https://github.com/evroon |
|||
- name: fastapi-tutorial |
|||
html_url: https://github.com/liaogx/fastapi-tutorial |
|||
stars: 1265 |
|||
stars: 1297 |
|||
owner_login: liaogx |
|||
owner_html_url: https://github.com/liaogx |
|||
- name: fastapi_best_architecture |
|||
html_url: https://github.com/fastapi-practices/fastapi_best_architecture |
|||
stars: 1242 |
|||
owner_login: fastapi-practices |
|||
owner_html_url: https://github.com/fastapi-practices |
|||
- name: fastapi-code-generator |
|||
html_url: https://github.com/koxudaxi/fastapi-code-generator |
|||
stars: 1216 |
|||
stars: 1241 |
|||
owner_login: koxudaxi |
|||
owner_html_url: https://github.com/koxudaxi |
|||
- name: bolt-python |
|||
html_url: https://github.com/slackapi/bolt-python |
|||
stars: 1190 |
|||
owner_login: slackapi |
|||
owner_html_url: https://github.com/slackapi |
|||
- name: fastcrud |
|||
html_url: https://github.com/benavlabs/fastcrud |
|||
stars: 1169 |
|||
stars: 1236 |
|||
owner_login: benavlabs |
|||
owner_html_url: https://github.com/benavlabs |
|||
- name: prometheus-fastapi-instrumentator |
|||
html_url: https://github.com/trallnag/prometheus-fastapi-instrumentator |
|||
stars: 1167 |
|||
stars: 1217 |
|||
owner_login: trallnag |
|||
owner_html_url: https://github.com/trallnag |
|||
- name: fastapi_production_template |
|||
html_url: https://github.com/zhanymkanov/fastapi_production_template |
|||
stars: 1165 |
|||
owner_login: zhanymkanov |
|||
owner_html_url: https://github.com/zhanymkanov |
|||
- name: bolt-python |
|||
html_url: https://github.com/slackapi/bolt-python |
|||
stars: 1209 |
|||
owner_login: slackapi |
|||
owner_html_url: https://github.com/slackapi |
|||
- name: bedrock-chat |
|||
html_url: https://github.com/aws-samples/bedrock-chat |
|||
stars: 1163 |
|||
stars: 1199 |
|||
owner_login: aws-samples |
|||
owner_html_url: https://github.com/aws-samples |
|||
- name: fastapi_production_template |
|||
html_url: https://github.com/zhanymkanov/fastapi_production_template |
|||
stars: 1182 |
|||
owner_login: zhanymkanov |
|||
owner_html_url: https://github.com/zhanymkanov |
|||
- name: langchain-extract |
|||
html_url: https://github.com/langchain-ai/langchain-extract |
|||
stars: 1142 |
|||
stars: 1162 |
|||
owner_login: langchain-ai |
|||
owner_html_url: https://github.com/langchain-ai |
|||
- name: odmantic |
|||
html_url: https://github.com/art049/odmantic |
|||
stars: 1121 |
|||
owner_login: art049 |
|||
owner_html_url: https://github.com/art049 |
|||
- name: fastapi_best_architecture |
|||
html_url: https://github.com/fastapi-practices/fastapi_best_architecture |
|||
stars: 1118 |
|||
owner_login: fastapi-practices |
|||
owner_html_url: https://github.com/fastapi-practices |
|||
- name: fastapi-langgraph-agent-production-ready-template |
|||
html_url: https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template |
|||
stars: 1150 |
|||
owner_login: wassim249 |
|||
owner_html_url: https://github.com/wassim249 |
|||
- name: fastapi-alembic-sqlmodel-async |
|||
html_url: https://github.com/jonra1993/fastapi-alembic-sqlmodel-async |
|||
stars: 1116 |
|||
stars: 1145 |
|||
owner_login: jonra1993 |
|||
owner_html_url: https://github.com/jonra1993 |
|||
- name: FastAPI-boilerplate |
|||
html_url: https://github.com/benavlabs/FastAPI-boilerplate |
|||
stars: 1070 |
|||
owner_login: benavlabs |
|||
owner_html_url: https://github.com/benavlabs |
|||
- name: odmantic |
|||
html_url: https://github.com/art049/odmantic |
|||
stars: 1130 |
|||
owner_login: art049 |
|||
owner_html_url: https://github.com/art049 |
|||
- name: restish |
|||
html_url: https://github.com/rest-sh/restish |
|||
stars: 1069 |
|||
stars: 1107 |
|||
owner_login: rest-sh |
|||
owner_html_url: https://github.com/rest-sh |
|||
- name: fastapi-scaff |
|||
html_url: https://github.com/atpuxiner/fastapi-scaff |
|||
stars: 1052 |
|||
owner_login: atpuxiner |
|||
owner_html_url: https://github.com/atpuxiner |
|||
- name: runhouse |
|||
html_url: https://github.com/run-house/runhouse |
|||
stars: 1037 |
|||
stars: 1043 |
|||
owner_login: run-house |
|||
owner_html_url: https://github.com/run-house |
|||
- name: flock |
|||
html_url: https://github.com/Onelevenvy/flock |
|||
stars: 1010 |
|||
owner_login: Onelevenvy |
|||
owner_html_url: https://github.com/Onelevenvy |
|||
- name: autollm |
|||
html_url: https://github.com/viddexa/autollm |
|||
stars: 994 |
|||
stars: 995 |
|||
owner_login: viddexa |
|||
owner_html_url: https://github.com/viddexa |
|||
- name: lanarky |
|||
html_url: https://github.com/ajndkr/lanarky |
|||
stars: 992 |
|||
stars: 994 |
|||
owner_login: ajndkr |
|||
owner_html_url: https://github.com/ajndkr |
|||
- name: authx |
|||
html_url: https://github.com/yezz123/authx |
|||
stars: 953 |
|||
stars: 978 |
|||
owner_login: yezz123 |
|||
owner_html_url: https://github.com/yezz123 |
|||
- name: secure |
|||
html_url: https://github.com/TypeError/secure |
|||
stars: 941 |
|||
stars: 942 |
|||
owner_login: TypeError |
|||
owner_html_url: https://github.com/TypeError |
|||
- name: titiler |
|||
html_url: https://github.com/developmentseed/titiler |
|||
stars: 940 |
|||
owner_login: developmentseed |
|||
owner_html_url: https://github.com/developmentseed |
|||
- name: energy-forecasting |
|||
html_url: https://github.com/iusztinpaul/energy-forecasting |
|||
stars: 928 |
|||
stars: 937 |
|||
owner_login: iusztinpaul |
|||
owner_html_url: https://github.com/iusztinpaul |
|||
- name: langcorn |
|||
html_url: https://github.com/msoedov/langcorn |
|||
stars: 927 |
|||
stars: 933 |
|||
owner_login: msoedov |
|||
owner_html_url: https://github.com/msoedov |
|||
- name: titiler |
|||
html_url: https://github.com/developmentseed/titiler |
|||
stars: 901 |
|||
owner_login: developmentseed |
|||
owner_html_url: https://github.com/developmentseed |
|||
- name: flock |
|||
html_url: https://github.com/Onelevenvy/flock |
|||
stars: 896 |
|||
owner_login: Onelevenvy |
|||
owner_html_url: https://github.com/Onelevenvy |
|||
- name: fastapi-langgraph-agent-production-ready-template |
|||
html_url: https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template |
|||
stars: 896 |
|||
owner_login: wassim249 |
|||
owner_html_url: https://github.com/wassim249 |
|||
- name: marker-api |
|||
html_url: https://github.com/adithya-s-k/marker-api |
|||
stars: 875 |
|||
owner_login: adithya-s-k |
|||
owner_html_url: https://github.com/adithya-s-k |
|||
- name: httpdbg |
|||
html_url: https://github.com/cle-b/httpdbg |
|||
stars: 870 |
|||
owner_login: cle-b |
|||
owner_html_url: https://github.com/cle-b |
|||
- name: fastapi-do-zero |
|||
html_url: https://github.com/dunossauro/fastapi-do-zero |
|||
stars: 855 |
|||
stars: 892 |
|||
owner_login: dunossauro |
|||
owner_html_url: https://github.com/dunossauro |
|||
- name: ludic |
|||
html_url: https://github.com/getludic/ludic |
|||
stars: 849 |
|||
owner_login: getludic |
|||
owner_html_url: https://github.com/getludic |
|||
- name: fastapi-observability |
|||
html_url: https://github.com/blueswen/fastapi-observability |
|||
stars: 837 |
|||
owner_login: blueswen |
|||
owner_html_url: https://github.com/blueswen |
|||
- name: fastapi-scaf |
|||
html_url: https://github.com/atpuxiner/fastapi-scaf |
|||
stars: 821 |
|||
owner_login: atpuxiner |
|||
owner_html_url: https://github.com/atpuxiner |
|||
- name: starlette-admin |
|||
html_url: https://github.com/jowilf/starlette-admin |
|||
stars: 808 |
|||
owner_login: jowilf |
|||
owner_html_url: https://github.com/jowilf |
|||
- name: fastapi-mail |
|||
html_url: https://github.com/sabuhish/fastapi-mail |
|||
stars: 807 |
|||
owner_login: sabuhish |
|||
owner_html_url: https://github.com/sabuhish |
|||
- name: aktools |
|||
html_url: https://github.com/akfamily/aktools |
|||
stars: 796 |
|||
owner_login: akfamily |
|||
owner_html_url: https://github.com/akfamily |
|||
- name: marker-api |
|||
html_url: https://github.com/adithya-s-k/marker-api |
|||
stars: 890 |
|||
owner_login: adithya-s-k |
|||
owner_html_url: https://github.com/adithya-s-k |
|||
- name: RuoYi-Vue3-FastAPI |
|||
html_url: https://github.com/insistence/RuoYi-Vue3-FastAPI |
|||
stars: 782 |
|||
stars: 884 |
|||
owner_login: insistence |
|||
owner_html_url: https://github.com/insistence |
|||
- name: aktools |
|||
html_url: https://github.com/akfamily/aktools |
|||
stars: 880 |
|||
owner_login: akfamily |
|||
owner_html_url: https://github.com/akfamily |
|||
- name: fastapi-observability |
|||
html_url: https://github.com/blueswen/fastapi-observability |
|||
stars: 880 |
|||
owner_login: blueswen |
|||
owner_html_url: https://github.com/blueswen |
|||
- name: httpdbg |
|||
html_url: https://github.com/cle-b/httpdbg |
|||
stars: 876 |
|||
owner_login: cle-b |
|||
owner_html_url: https://github.com/cle-b |
|||
|
|||
@ -1,3 +1,3 @@ |
|||
# About |
|||
# About { #about } |
|||
|
|||
About FastAPI, its design, inspiration and more. 🤓 |
|||
|
|||
@ -1,34 +1,42 @@ |
|||
# Generate Clients |
|||
# Generating SDKs { #generating-sdks } |
|||
|
|||
As **FastAPI** is based on the OpenAPI specification, you get automatic compatibility with many tools, including the automatic API docs (provided by Swagger UI). |
|||
Because **FastAPI** is based on the **OpenAPI** specification, its APIs can be described in a standard format that many tools understand. |
|||
|
|||
One particular advantage that is not necessarily obvious is that you can **generate clients** (sometimes called <abbr title="Software Development Kits">**SDKs**</abbr> ) for your API, for many different **programming languages**. |
|||
This makes it easy to generate up-to-date **documentation**, client libraries (<abbr title="Software Development Kits">**SDKs**</abbr>) in multiple languages, and **testing** or **automation workflows** that stay in sync with your code. |
|||
|
|||
## OpenAPI Client Generators |
|||
In this guide, you'll learn how to generate a **TypeScript SDK** for your FastAPI backend. |
|||
|
|||
There are many tools to generate clients from **OpenAPI**. |
|||
## Open Source SDK Generators { #open-source-sdk-generators } |
|||
|
|||
A common tool is <a href="https://openapi-generator.tech/" class="external-link" target="_blank">OpenAPI Generator</a>. |
|||
A versatile option is the <a href="https://openapi-generator.tech/" class="external-link" target="_blank">OpenAPI Generator</a>, which supports **many programming languages** and can generate SDKs from your OpenAPI specification. |
|||
|
|||
If you are building a **frontend**, a very interesting alternative is <a href="https://github.com/hey-api/openapi-ts" class="external-link" target="_blank">openapi-ts</a>. |
|||
For **TypeScript clients**, <a href="https://heyapi.dev/" class="external-link" target="_blank">Hey API</a> is a purpose-built solution, providing an optimized experience for the TypeScript ecosystem. |
|||
|
|||
## Client and SDK Generators - Sponsor |
|||
You can discover more SDK generators on <a href="https://openapi.tools/#sdk" class="external-link" target="_blank">OpenAPI.Tools</a>. |
|||
|
|||
There are also some **company-backed** Client and SDK generators based on OpenAPI (FastAPI), in some cases they can offer you **additional features** on top of high-quality generated SDKs/clients. |
|||
/// tip |
|||
|
|||
FastAPI automatically generates **OpenAPI 3.1** specifications, so any tool you use must support this version. |
|||
|
|||
/// |
|||
|
|||
## SDK Generators from FastAPI Sponsors { #sdk-generators-from-fastapi-sponsors } |
|||
|
|||
This section highlights **venture-backed** and **company-supported** solutions from companies that sponsor FastAPI. These products provide **additional features** and **integrations** on top of high-quality generated SDKs. |
|||
|
|||
Some of them also ✨ [**sponsor FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨, this ensures the continued and healthy **development** of FastAPI and its **ecosystem**. |
|||
By ✨ [**sponsoring FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨, these companies help ensure the framework and its **ecosystem** remain healthy and **sustainable**. |
|||
|
|||
And it shows their true commitment to FastAPI and its **community** (you), as they not only want to provide you a **good service** but also want to make sure you have a **good and healthy framework**, FastAPI. 🙇 |
|||
Their sponsorship also demonstrates a strong commitment to the FastAPI **community** (you), showing that they care not only about offering a **great service** but also about supporting a **robust and thriving framework**, FastAPI. 🙇 |
|||
|
|||
For example, you might want to try: |
|||
|
|||
* <a href="https://speakeasy.com/editor?utm_source=fastapi+repo&utm_medium=github+sponsorship" class="external-link" target="_blank">Speakeasy</a> |
|||
* <a href="https://www.stainlessapi.com/?utm_source=fastapi&utm_medium=referral" class="external-link" target="_blank">Stainless</a> |
|||
* <a href="https://www.stainless.com/?utm_source=fastapi&utm_medium=referral" class="external-link" target="_blank">Stainless</a> |
|||
* <a href="https://developers.liblab.com/tutorials/sdk-for-fastapi?utm_source=fastapi" class="external-link" target="_blank">liblab</a> |
|||
|
|||
There are also several other companies offering similar services that you can search and find online. 🤓 |
|||
Some of these solutions may also be open source or offer free tiers, so you can try them without a financial commitment. Other commercial SDK generators are available and can be found online. 🤓 |
|||
|
|||
## Generate a TypeScript Frontend Client |
|||
## Create a TypeScript SDK { #create-a-typescript-sdk } |
|||
|
|||
Let's start with a simple FastAPI application: |
|||
|
|||
@ -36,80 +44,33 @@ Let's start with a simple FastAPI application: |
|||
|
|||
Notice that the *path operations* define the models they use for request payload and response payload, using the models `Item` and `ResponseMessage`. |
|||
|
|||
### API Docs |
|||
### API Docs { #api-docs } |
|||
|
|||
If you go to the API docs, you will see that it has the **schemas** for the data to be sent in requests and received in responses: |
|||
If you go to `/docs`, you will see that it has the **schemas** for the data to be sent in requests and received in responses: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image01.png"> |
|||
|
|||
You can see those schemas because they were declared with the models in the app. |
|||
|
|||
That information is available in the app's **OpenAPI schema**, and then shown in the API docs (by Swagger UI). |
|||
|
|||
And that same information from the models that is included in OpenAPI is what can be used to **generate the client code**. |
|||
|
|||
### Generate a TypeScript Client |
|||
|
|||
Now that we have the app with the models, we can generate the client code for the frontend. |
|||
|
|||
#### Install `openapi-ts` |
|||
|
|||
You can install `openapi-ts` in your frontend code with: |
|||
|
|||
<div class="termy"> |
|||
That information is available in the app's **OpenAPI schema**, and then shown in the API docs. |
|||
|
|||
```console |
|||
$ npm install @hey-api/openapi-ts --save-dev |
|||
That same information from the models that is included in OpenAPI is what can be used to **generate the client code**. |
|||
|
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
#### Generate Client Code |
|||
|
|||
To generate the client code you can use the command line application `openapi-ts` that would now be installed. |
|||
|
|||
Because it is installed in the local project, you probably wouldn't be able to call that command directly, but you would put it on your `package.json` file. |
|||
|
|||
It could look like this: |
|||
### Hey API { #hey-api } |
|||
|
|||
```JSON hl_lines="7" |
|||
{ |
|||
"name": "frontend-app", |
|||
"version": "1.0.0", |
|||
"description": "", |
|||
"main": "index.js", |
|||
"scripts": { |
|||
"generate-client": "openapi-ts --input http://localhost:8000/openapi.json --output ./src/client --client axios" |
|||
}, |
|||
"author": "", |
|||
"license": "", |
|||
"devDependencies": { |
|||
"@hey-api/openapi-ts": "^0.27.38", |
|||
"typescript": "^4.6.2" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
After having that NPM `generate-client` script there, you can run it with: |
|||
|
|||
<div class="termy"> |
|||
Once we have a FastAPI app with the models, we can use Hey API to generate a TypeScript client. The fastest way to do that is via npx. |
|||
|
|||
```console |
|||
$ npm run generate-client |
|||
|
|||
[email protected] generate-client /home/user/code/frontend-app |
|||
> openapi-ts --input http://localhost:8000/openapi.json --output ./src/client --client axios |
|||
```sh |
|||
npx @hey-api/openapi-ts -i http://localhost:8000/openapi.json -o src/client |
|||
``` |
|||
|
|||
</div> |
|||
This will generate a TypeScript SDK in `./src/client`. |
|||
|
|||
That command will generate code in `./src/client` and will use `axios` (the frontend HTTP library) internally. |
|||
You can learn how to <a href="https://heyapi.dev/openapi-ts/get-started" class="external-link" target="_blank">install `@hey-api/openapi-ts`</a> and read about the <a href="https://heyapi.dev/openapi-ts/output" class="external-link" target="_blank">generated output</a> on their website. |
|||
|
|||
### Try Out the Client Code |
|||
### Using the SDK { #using-the-sdk } |
|||
|
|||
Now you can import and use the client code, it could look like this, notice that you get autocompletion for the methods: |
|||
Now you can import and use the client code. It could look like this, notice that you get autocompletion for the methods: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image02.png"> |
|||
|
|||
@ -131,30 +92,30 @@ The response object will also have autocompletion: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image05.png"> |
|||
|
|||
## FastAPI App with Tags |
|||
## FastAPI App with Tags { #fastapi-app-with-tags } |
|||
|
|||
In many cases your FastAPI app will be bigger, and you will probably use tags to separate different groups of *path operations*. |
|||
In many cases, your FastAPI app will be bigger, and you will probably use tags to separate different groups of *path operations*. |
|||
|
|||
For example, you could have a section for **items** and another section for **users**, and they could be separated by tags: |
|||
|
|||
{* ../../docs_src/generate_clients/tutorial002_py39.py hl[21,26,34] *} |
|||
|
|||
### Generate a TypeScript Client with Tags |
|||
### Generate a TypeScript Client with Tags { #generate-a-typescript-client-with-tags } |
|||
|
|||
If you generate a client for a FastAPI app using tags, it will normally also separate the client code based on the tags. |
|||
|
|||
This way you will be able to have things ordered and grouped correctly for the client code: |
|||
This way, you will be able to have things ordered and grouped correctly for the client code: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image06.png"> |
|||
|
|||
In this case you have: |
|||
In this case, you have: |
|||
|
|||
* `ItemsService` |
|||
* `UsersService` |
|||
|
|||
### Client Method Names |
|||
### Client Method Names { #client-method-names } |
|||
|
|||
Right now the generated method names like `createItemItemsPost` don't look very clean: |
|||
Right now, the generated method names like `createItemItemsPost` don't look very clean: |
|||
|
|||
```TypeScript |
|||
ItemsService.createItemItemsPost({name: "Plumbus", price: 5}) |
|||
@ -166,17 +127,17 @@ OpenAPI requires that each operation ID is unique across all the *path operation |
|||
|
|||
But I'll show you how to improve that next. 🤓 |
|||
|
|||
## Custom Operation IDs and Better Method Names |
|||
## Custom Operation IDs and Better Method Names { #custom-operation-ids-and-better-method-names } |
|||
|
|||
You can **modify** the way these operation IDs are **generated** to make them simpler and have **simpler method names** in the clients. |
|||
|
|||
In this case you will have to ensure that each operation ID is **unique** in some other way. |
|||
In this case, you will have to ensure that each operation ID is **unique** in some other way. |
|||
|
|||
For example, you could make sure that each *path operation* has a tag, and then generate the operation ID based on the **tag** and the *path operation* **name** (the function name). |
|||
|
|||
### Custom Generate Unique ID Function |
|||
### Custom Generate Unique ID Function { #custom-generate-unique-id-function } |
|||
|
|||
FastAPI uses a **unique ID** for each *path operation*, it is used for the **operation ID** and also for the names of any needed custom models, for requests or responses. |
|||
FastAPI uses a **unique ID** for each *path operation*, which is used for the **operation ID** and also for the names of any needed custom models, for requests or responses. |
|||
|
|||
You can customize that function. It takes an `APIRoute` and outputs a string. |
|||
|
|||
@ -186,15 +147,15 @@ You can then pass that custom function to **FastAPI** as the `generate_unique_id |
|||
|
|||
{* ../../docs_src/generate_clients/tutorial003_py39.py hl[6:7,10] *} |
|||
|
|||
### Generate a TypeScript Client with Custom Operation IDs |
|||
### Generate a TypeScript Client with Custom Operation IDs { #generate-a-typescript-client-with-custom-operation-ids } |
|||
|
|||
Now if you generate the client again, you will see that it has the improved method names: |
|||
Now, if you generate the client again, you will see that it has the improved method names: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image07.png"> |
|||
|
|||
As you see, the method names now have the tag and then the function name, now they don't include information from the URL path and the HTTP operation. |
|||
|
|||
### Preprocess the OpenAPI Specification for the Client Generator |
|||
### Preprocess the OpenAPI Specification for the Client Generator { #preprocess-the-openapi-specification-for-the-client-generator } |
|||
|
|||
The generated code still has some **duplicated information**. |
|||
|
|||
@ -202,7 +163,7 @@ We already know that this method is related to the **items** because that word i |
|||
|
|||
We will probably still want to keep it for OpenAPI in general, as that will ensure that the operation IDs are **unique**. |
|||
|
|||
But for the generated client we could **modify** the OpenAPI operation IDs right before generating the clients, just to make those method names nicer and **cleaner**. |
|||
But for the generated client, we could **modify** the OpenAPI operation IDs right before generating the clients, just to make those method names nicer and **cleaner**. |
|||
|
|||
We could download the OpenAPI JSON to a file `openapi.json` and then we could **remove that prefixed tag** with a script like this: |
|||
|
|||
@ -218,35 +179,21 @@ We could download the OpenAPI JSON to a file `openapi.json` and then we could ** |
|||
|
|||
With that, the operation IDs would be renamed from things like `items-get_items` to just `get_items`, that way the client generator can generate simpler method names. |
|||
|
|||
### Generate a TypeScript Client with the Preprocessed OpenAPI |
|||
|
|||
Now as the end result is in a file `openapi.json`, you would modify the `package.json` to use that local file, for example: |
|||
|
|||
```JSON hl_lines="7" |
|||
{ |
|||
"name": "frontend-app", |
|||
"version": "1.0.0", |
|||
"description": "", |
|||
"main": "index.js", |
|||
"scripts": { |
|||
"generate-client": "openapi-ts --input ./openapi.json --output ./src/client --client axios" |
|||
}, |
|||
"author": "", |
|||
"license": "", |
|||
"devDependencies": { |
|||
"@hey-api/openapi-ts": "^0.27.38", |
|||
"typescript": "^4.6.2" |
|||
} |
|||
} |
|||
### Generate a TypeScript Client with the Preprocessed OpenAPI { #generate-a-typescript-client-with-the-preprocessed-openapi } |
|||
|
|||
Since the end result is now in an `openapi.json` file, you need to update your input location: |
|||
|
|||
```sh |
|||
npx @hey-api/openapi-ts -i ./openapi.json -o src/client |
|||
``` |
|||
|
|||
After generating the new client, you would now have **clean method names**, with all the **autocompletion**, **inline errors**, etc: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image08.png"> |
|||
|
|||
## Benefits |
|||
## Benefits { #benefits } |
|||
|
|||
When using the automatically generated clients you would get **autocompletion** for: |
|||
When using the automatically generated clients, you would get **autocompletion** for: |
|||
|
|||
* Methods. |
|||
* Request payloads in the body, query parameters, etc. |
|||
@ -256,6 +203,6 @@ You would also have **inline errors** for everything. |
|||
|
|||
And whenever you update the backend code, and **regenerate** the frontend, it would have any new *path operations* available as methods, the old ones removed, and any other change would be reflected on the generated code. 🤓 |
|||
|
|||
This also means that if something changed it will be **reflected** on the client code automatically. And if you **build** the client it will error out if you have any **mismatch** in the data used. |
|||
This also means that if something changed, it will be **reflected** on the client code automatically. And if you **build** the client, it will error out if you have any **mismatch** in the data used. |
|||
|
|||
So, you would **detect many errors** very early in the development cycle instead of having to wait for the errors to show up to your final users in production and then trying to debug where the problem is. ✨ |
|||
|
|||
@ -1,4 +1,4 @@ |
|||
# Settings and Environment Variables |
|||
# Settings and Environment Variables { #settings-and-environment-variables } |
|||
|
|||
In many cases your application could need some external settings or configurations, for example secret keys, database credentials, credentials for email services, etc. |
|||
|
|||
@ -12,17 +12,17 @@ To understand environment variables you can read [Environment Variables](../envi |
|||
|
|||
/// |
|||
|
|||
## Types and validation |
|||
## Types and validation { #types-and-validation } |
|||
|
|||
These environment variables can only handle text strings, as they are external to Python and have to be compatible with other programs and the rest of the system (and even with different operating systems, as Linux, Windows, macOS). |
|||
|
|||
That means that any value read in Python from an environment variable will be a `str`, and any conversion to a different type or any validation has to be done in code. |
|||
|
|||
## Pydantic `Settings` |
|||
## Pydantic `Settings` { #pydantic-settings } |
|||
|
|||
Fortunately, Pydantic provides a great utility to handle these settings coming from environment variables with <a href="https://docs.pydantic.dev/latest/concepts/pydantic_settings/" class="external-link" target="_blank">Pydantic: Settings management</a>. |
|||
|
|||
### Install `pydantic-settings` |
|||
### Install `pydantic-settings` { #install-pydantic-settings } |
|||
|
|||
First, make sure you create your [virtual environment](../virtual-environments.md){.internal-link target=_blank}, activate it, and then install the `pydantic-settings` package: |
|||
|
|||
@ -52,7 +52,7 @@ In Pydantic v1 it came included with the main package. Now it is distributed as |
|||
|
|||
/// |
|||
|
|||
### Create the `Settings` object |
|||
### Create the `Settings` object { #create-the-settings-object } |
|||
|
|||
Import `BaseSettings` from Pydantic and create a sub-class, very much like with a Pydantic model. |
|||
|
|||
@ -88,13 +88,13 @@ Then, when you create an instance of that `Settings` class (in this case, in the |
|||
|
|||
Next it will convert and validate the data. So, when you use that `settings` object, you will have data of the types you declared (e.g. `items_per_user` will be an `int`). |
|||
|
|||
### Use the `settings` |
|||
### Use the `settings` { #use-the-settings } |
|||
|
|||
Then you can use the new `settings` object in your application: |
|||
|
|||
{* ../../docs_src/settings/tutorial001.py hl[18:20] *} |
|||
|
|||
### Run the server |
|||
### Run the server { #run-the-server } |
|||
|
|||
Next, you would run the server passing the configurations as environment variables, for example you could set an `ADMIN_EMAIL` and `APP_NAME` with: |
|||
|
|||
@ -120,7 +120,7 @@ The `app_name` would be `"ChimichangApp"`. |
|||
|
|||
And the `items_per_user` would keep its default value of `50`. |
|||
|
|||
## Settings in another module |
|||
## Settings in another module { #settings-in-another-module } |
|||
|
|||
You could put those settings in another module file as you saw in [Bigger Applications - Multiple Files](../tutorial/bigger-applications.md){.internal-link target=_blank}. |
|||
|
|||
@ -138,13 +138,13 @@ You would also need a file `__init__.py` as you saw in [Bigger Applications - Mu |
|||
|
|||
/// |
|||
|
|||
## Settings in a dependency |
|||
## Settings in a dependency { #settings-in-a-dependency } |
|||
|
|||
In some occasions it might be useful to provide the settings from a dependency, instead of having a global object with `settings` that is used everywhere. |
|||
|
|||
This could be especially useful during testing, as it's very easy to override a dependency with your own custom settings. |
|||
|
|||
### The config file |
|||
### The config file { #the-config-file } |
|||
|
|||
Coming from the previous example, your `config.py` file could look like: |
|||
|
|||
@ -152,7 +152,7 @@ Coming from the previous example, your `config.py` file could look like: |
|||
|
|||
Notice that now we don't create a default instance `settings = Settings()`. |
|||
|
|||
### The main app file |
|||
### The main app file { #the-main-app-file } |
|||
|
|||
Now we create a dependency that returns a new `config.Settings()`. |
|||
|
|||
@ -170,7 +170,7 @@ And then we can require it from the *path operation function* as a dependency an |
|||
|
|||
{* ../../docs_src/settings/app02_an_py39/main.py hl[17,19:21] *} |
|||
|
|||
### Settings and testing |
|||
### Settings and testing { #settings-and-testing } |
|||
|
|||
Then it would be very easy to provide a different settings object during testing by creating a dependency override for `get_settings`: |
|||
|
|||
@ -180,7 +180,7 @@ In the dependency override we set a new value for the `admin_email` when creatin |
|||
|
|||
Then we can test that it is used. |
|||
|
|||
## Reading a `.env` file |
|||
## Reading a `.env` file { #reading-a-env-file } |
|||
|
|||
If you have many settings that possibly change a lot, maybe in different environments, it might be useful to put them on a file and then read them from it as if they were environment variables. |
|||
|
|||
@ -202,7 +202,7 @@ For this to work, you need to `pip install python-dotenv`. |
|||
|
|||
/// |
|||
|
|||
### The `.env` file |
|||
### The `.env` file { #the-env-file } |
|||
|
|||
You could have a `.env` file with: |
|||
|
|||
@ -211,7 +211,7 @@ ADMIN_EMAIL="[email protected]" |
|||
APP_NAME="ChimichangApp" |
|||
``` |
|||
|
|||
### Read settings from `.env` |
|||
### Read settings from `.env` { #read-settings-from-env } |
|||
|
|||
And then update your `config.py` with: |
|||
|
|||
@ -247,7 +247,7 @@ In Pydantic version 1 the configuration was done in an internal class `Config`, |
|||
|
|||
Here we define the config `env_file` inside of your Pydantic `Settings` class, and set the value to the filename with the dotenv file we want to use. |
|||
|
|||
### Creating the `Settings` only once with `lru_cache` |
|||
### Creating the `Settings` only once with `lru_cache` { #creating-the-settings-only-once-with-lru-cache } |
|||
|
|||
Reading a file from disk is normally a costly (slow) operation, so you probably want to do it only once and then reuse the same settings object, instead of reading it for each request. |
|||
|
|||
@ -274,7 +274,7 @@ But as we are using the `@lru_cache` decorator on top, the `Settings` object wil |
|||
|
|||
Then for any subsequent call of `get_settings()` in the dependencies for the next requests, instead of executing the internal code of `get_settings()` and creating a new `Settings` object, it will return the same object that was returned on the first call, again and again. |
|||
|
|||
#### `lru_cache` Technical Details |
|||
#### `lru_cache` Technical Details { #lru-cache-technical-details } |
|||
|
|||
`@lru_cache` modifies the function it decorates to return the same value that was returned the first time, instead of computing it again, executing the code of the function every time. |
|||
|
|||
@ -337,7 +337,7 @@ That way, it behaves almost as if it was just a global variable. But as it uses |
|||
|
|||
`@lru_cache` is part of `functools` which is part of Python's standard library, you can read more about it in the <a href="https://docs.python.org/3/library/functools.html#functools.lru_cache" class="external-link" target="_blank">Python docs for `@lru_cache`</a>. |
|||
|
|||
## Recap |
|||
## Recap { #recap } |
|||
|
|||
You can use Pydantic Settings to handle the settings or configurations for your application, with all the power of Pydantic models. |
|||
|
|||
|
|||
@ -1,5 +1,12 @@ |
|||
# Testing Events: startup - shutdown |
|||
# Testing Events: lifespan and startup - shutdown { #testing-events-lifespan-and-startup-shutdown } |
|||
|
|||
When you need your event handlers (`startup` and `shutdown`) to run in your tests, you can use the `TestClient` with a `with` statement: |
|||
When you need `lifespan` to run in your tests, you can use the `TestClient` with a `with` statement: |
|||
|
|||
{* ../../docs_src/app_testing/tutorial004.py hl[9:15,18,27:28,30:32,41:43] *} |
|||
|
|||
|
|||
You can read more details about the ["Running lifespan in tests in the official Starlette documentation site."](https://www.starlette.io/lifespan/#running-lifespan-in-tests) |
|||
|
|||
For the deprecated `startup` and `shutdown` events, you can use the `TestClient` as follows: |
|||
|
|||
{* ../../docs_src/app_testing/tutorial003.py hl[9:12,20:24] *} |
|||
|
|||
@ -1,39 +1,39 @@ |
|||
# General - How To - Recipes |
|||
# General - How To - Recipes { #general-how-to-recipes } |
|||
|
|||
Here are several pointers to other places in the docs, for general or frequent questions. |
|||
|
|||
## Filter Data - Security |
|||
## Filter Data - Security { #filter-data-security } |
|||
|
|||
To ensure that you don't return more data than you should, read the docs for [Tutorial - Response Model - Return Type](../tutorial/response-model.md){.internal-link target=_blank}. |
|||
|
|||
## Documentation Tags - OpenAPI |
|||
## Documentation Tags - OpenAPI { #documentation-tags-openapi } |
|||
|
|||
To add tags to your *path operations*, and group them in the docs UI, read the docs for [Tutorial - Path Operation Configurations - Tags](../tutorial/path-operation-configuration.md#tags){.internal-link target=_blank}. |
|||
|
|||
## Documentation Summary and Description - OpenAPI |
|||
## Documentation Summary and Description - OpenAPI { #documentation-summary-and-description-openapi } |
|||
|
|||
To add a summary and description to your *path operations*, and show them in the docs UI, read the docs for [Tutorial - Path Operation Configurations - Summary and Description](../tutorial/path-operation-configuration.md#summary-and-description){.internal-link target=_blank}. |
|||
|
|||
## Documentation Response description - OpenAPI |
|||
## Documentation Response description - OpenAPI { #documentation-response-description-openapi } |
|||
|
|||
To define the description of the response, shown in the docs UI, read the docs for [Tutorial - Path Operation Configurations - Response description](../tutorial/path-operation-configuration.md#response-description){.internal-link target=_blank}. |
|||
|
|||
## Documentation Deprecate a *Path Operation* - OpenAPI |
|||
## Documentation Deprecate a *Path Operation* - OpenAPI { #documentation-deprecate-a-path-operation-openapi } |
|||
|
|||
To deprecate a *path operation*, and show it in the docs UI, read the docs for [Tutorial - Path Operation Configurations - Deprecation](../tutorial/path-operation-configuration.md#deprecate-a-path-operation){.internal-link target=_blank}. |
|||
|
|||
## Convert any Data to JSON-compatible |
|||
## Convert any Data to JSON-compatible { #convert-any-data-to-json-compatible } |
|||
|
|||
To convert any data to JSON-compatible, read the docs for [Tutorial - JSON Compatible Encoder](../tutorial/encoder.md){.internal-link target=_blank}. |
|||
|
|||
## OpenAPI Metadata - Docs |
|||
## OpenAPI Metadata - Docs { #openapi-metadata-docs } |
|||
|
|||
To add metadata to your OpenAPI schema, including a license, version, contact, etc, read the docs for [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md){.internal-link target=_blank}. |
|||
|
|||
## OpenAPI Custom URL |
|||
## OpenAPI Custom URL { #openapi-custom-url } |
|||
|
|||
To customize the OpenAPI URL (or remove it), read the docs for [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md#openapi-url){.internal-link target=_blank}. |
|||
|
|||
## OpenAPI Docs URLs |
|||
## OpenAPI Docs URLs { #openapi-docs-urls } |
|||
|
|||
To update the URLs used for the automatically generated docs user interfaces, read the docs for [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md#docs-urls){.internal-link target=_blank}. |
|||
|
|||
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue