1# Generando SDKs { #generating-sdks }23Como **FastAPI** está basado en la especificación **OpenAPI**, sus APIs se pueden describir en un formato estándar que muchas herramientas entienden.45Esto facilita generar **documentación** actualizada, paquetes de cliente (<abbr title="Software Development Kits - Kits de Desarrollo de Software">**SDKs**</abbr>) en múltiples lenguajes y **escribir pruebas** o **flujos de automatización** que se mantengan sincronizados con tu código.67En esta guía, aprenderás a generar un **SDK de TypeScript** para tu backend con FastAPI.89## Generadores de SDKs de código abierto { #open-source-sdk-generators }1011Una opción versátil es el [OpenAPI Generator](https://openapi-generator.tech/), que soporta **muchos lenguajes de programación** y puede generar SDKs a partir de tu especificación OpenAPI.1213Para **clientes de TypeScript**, [Hey API](https://heyapi.dev/) es una solución diseñada específicamente, que ofrece una experiencia optimizada para el ecosistema de TypeScript.1415Puedes descubrir más generadores de SDK en [OpenAPI.Tools](https://openapi.tools/categories/sdk-generators).1617/// tip | Consejo1819FastAPI genera automáticamente especificaciones **OpenAPI 3.1**, así que cualquier herramienta que uses debe soportar esta versión.2021///2223## Crea un SDK de TypeScript { #create-a-typescript-sdk }2425Empecemos con una aplicación simple de FastAPI:2627{* ../../docs_src/generate_clients/tutorial001_py310.py hl[7:9,12:13,16:17,21] *}2829Nota que las *path operations* definen los modelos que usan para el payload del request y el payload del response, usando los modelos `Item` y `ResponseMessage`.3031### Documentación de la API { #api-docs }3233Si vas a `/docs`, verás que tiene los **esquemas** para los datos a enviar en requests y recibir en responses:3435<img src="/img/tutorial/generate-clients/image01.png">3637Puedes ver esos esquemas porque fueron declarados con los modelos en la app.3839Esa información está disponible en el **OpenAPI schema** de la app, y luego se muestra en la documentación de la API.4041Esa misma información de los modelos que está incluida en OpenAPI es lo que puede usarse para **generar el código del cliente**.4243### Hey API { #hey-api }4445Una vez que tenemos una app de FastAPI con los modelos, podemos usar Hey API para generar un cliente de TypeScript. La forma más rápida de hacerlo es con npx.4647```sh48npx @hey-api/openapi-ts -i http://localhost:8000/openapi.json -o src/client49```5051Esto generará un SDK de TypeScript en `./src/client`.5253Puedes aprender cómo [instalar `@hey-api/openapi-ts`](https://heyapi.dev/openapi-ts/get-started) y leer sobre el [output generado](https://heyapi.dev/openapi-ts/output) en su sitio web.5455### Usar el SDK { #using-the-sdk }5657Ahora puedes importar y usar el código del cliente. Podría verse así, nota que tienes autocompletado para los métodos:5859<img src="/img/tutorial/generate-clients/image02.png">6061También obtendrás autocompletado para el payload a enviar:6263<img src="/img/tutorial/generate-clients/image03.png">6465/// tip | Consejo6667Nota el autocompletado para `name` y `price`, que fue definido en la aplicación de FastAPI, en el modelo `Item`.6869///7071Tendrás errores en línea para los datos que envíes:7273<img src="/img/tutorial/generate-clients/image04.png">7475El objeto de response también tendrá autocompletado:7677<img src="/img/tutorial/generate-clients/image05.png">7879## App de FastAPI con tags { #fastapi-app-with-tags }8081En muchos casos tu app de FastAPI será más grande, y probablemente usarás tags para separar diferentes grupos de *path operations*.8283Por ejemplo, podrías tener una sección para **items** y otra sección para **users**, y podrían estar separadas por tags:8485{* ../../docs_src/generate_clients/tutorial002_py310.py hl[21,26,34] *}8687### Genera un Cliente TypeScript con tags { #generate-a-typescript-client-with-tags }8889Si generas un cliente para una app de FastAPI usando tags, normalmente también separará el código del cliente basándose en los tags.9091De esta manera podrás tener las cosas ordenadas y agrupadas correctamente para el código del cliente:9293<img src="/img/tutorial/generate-clients/image06.png">9495En este caso tienes:9697* `ItemsService`98* `UsersService`99100### Nombres de los métodos del cliente { #client-method-names }101102Ahora mismo los nombres de los métodos generados como `createItemItemsPost` no se ven muy limpios:103104```TypeScript105ItemsService.createItemItemsPost({name: "Plumbus", price: 5})106```107108...eso es porque el generador del cliente usa el **operation ID** interno de OpenAPI para cada *path operation*.109110OpenAPI requiere que cada operation ID sea único a través de todas las *path operations*, por lo que FastAPI usa el **nombre de la función**, el **path**, y el **método/operación HTTP** para generar ese operation ID, porque de esa manera puede asegurarse de que los operation IDs sean únicos.111112Pero te mostraré cómo mejorar eso a continuación. 🤓113114## Operation IDs personalizados y mejores nombres de métodos { #custom-operation-ids-and-better-method-names }115116Puedes **modificar** la forma en que estos operation IDs son **generados** para hacerlos más simples y tener **nombres de métodos más simples** en los clientes.117118En este caso tendrás que asegurarte de que cada operation ID sea **único** de alguna otra manera.119120Por ejemplo, podrías asegurarte de que cada *path operation* tenga un tag, y luego generar el operation ID basado en el **tag** y el **nombre** de la *path operation* (el nombre de la función).121122### Función personalizada para generar ID único { #custom-generate-unique-id-function }123124FastAPI usa un **ID único** para cada *path operation*, se usa para el **operation ID** y también para los nombres de cualquier modelo personalizado necesario, para requests o responses.125126Puedes personalizar esa función. Toma un `APIRoute` y retorna un string.127128Por ejemplo, aquí está usando el primer tag (probablemente tendrás solo un tag) y el nombre de la *path operation* (el nombre de la función).129130Puedes entonces pasar esa función personalizada a **FastAPI** como el parámetro `generate_unique_id_function`:131132{* ../../docs_src/generate_clients/tutorial003_py310.py hl[6:7,10] *}133134### Genera un Cliente TypeScript con operation IDs personalizados { #generate-a-typescript-client-with-custom-operation-ids }135136Ahora, si generas el cliente de nuevo, verás que tiene los nombres de métodos mejorados:137138<img src="/img/tutorial/generate-clients/image07.png">139140Como ves, los nombres de métodos ahora tienen el tag y luego el nombre de la función, ahora no incluyen información del path de la URL y la operación HTTP.141142### Preprocesa la especificación OpenAPI para el generador de clientes { #preprocess-the-openapi-specification-for-the-client-generator }143144El código generado aún tiene algo de **información duplicada**.145146Ya sabemos que este método está relacionado con los **items** porque esa palabra está en el `ItemsService` (tomado del tag), pero aún tenemos el nombre del tag prefijado en el nombre del método también. 😕147148Probablemente aún querremos mantenerlo para OpenAPI en general, ya que eso asegurará que los operation IDs sean **únicos**.149150Pero para el cliente generado podríamos **modificar** los operation IDs de OpenAPI justo antes de generar los clientes, solo para hacer esos nombres de métodos más bonitos y **limpios**.151152Podríamos descargar el JSON de OpenAPI a un archivo `openapi.json` y luego podríamos **remover ese tag prefijado** con un script como este:153154{* ../../docs_src/generate_clients/tutorial004_py310.py *}155156//// tab | Node.js157158```Javascript159{!> ../../docs_src/generate_clients/tutorial004.js!}160```161162////163164Con eso, los operation IDs serían renombrados de cosas como `items-get_items` a solo `get_items`, de esa manera el generador del cliente puede generar nombres de métodos más simples.165166### Genera un Cliente TypeScript con el OpenAPI preprocesado { #generate-a-typescript-client-with-the-preprocessed-openapi }167168Como el resultado final ahora está en un archivo `openapi.json`, necesitas actualizar la ubicación de la entrada:169170```sh171npx @hey-api/openapi-ts -i ./openapi.json -o src/client172```173174Después de generar el nuevo cliente, ahora tendrías nombres de métodos **limpios**, con todo el **autocompletado**, **errores en línea**, etc:175176<img src="/img/tutorial/generate-clients/image08.png">177178## Beneficios { #benefits }179180Cuando uses los clientes generados automáticamente obtendrás **autocompletado** para:181182* Métodos.183* Payloads de request en el body, parámetros de query, etc.184* Payloads de response.185186También tendrás **errores en línea** para todo.187188Y cada vez que actualices el código del backend, y **regeneres** el frontend, tendrás las nuevas *path operations* disponibles como métodos, las antiguas eliminadas, y cualquier otro cambio se reflejará en el código generado. 🤓189190Esto también significa que si algo cambió será **reflejado** automáticamente en el código del cliente. Y si haces **build** del cliente, dará error si tienes algún **desajuste** en los datos utilizados.191192Así que, **detectarás muchos errores** muy temprano en el ciclo de desarrollo en lugar de tener que esperar a que los errores se muestren a tus usuarios finales en producción para luego intentar depurar dónde está el problema. ✨