Generando SDKs¶

ComoFastAPI está basado en la especificaciónOpenAPI, sus APIs se pueden describir en un formato estándar que muchas herramientas entienden.

Esto facilita generardocumentación actualizada, paquetes de cliente (SDKs) en múltiples lenguajes yescribir pruebas oflujos de automatización que se mantengan sincronizados con tu código.

En esta guía, aprenderás a generar unSDK de TypeScript para tu backend con FastAPI.

Generadores de SDKs de código abierto¶

Una opción versátil es elOpenAPI Generator, que soportamuchos lenguajes de programación y puede generar SDKs a partir de tu especificación OpenAPI.

Paraclientes de TypeScript,Hey API es una solución diseñada específicamente, que ofrece una experiencia optimizada para el ecosistema de TypeScript.

Puedes descubrir más generadores de SDK enOpenAPI.Tools.

Generadores de SDKs de sponsors de FastAPI¶

Esta sección destaca solucionesrespaldadas por empresas yventure-backed de compañías que sponsorean FastAPI. Estos productos ofrecenfuncionalidades adicionales eintegraciones además de SDKs generados de alta calidad.

Al ✨sponsorear FastAPI ✨, estas compañías ayudan a asegurar que el framework y suecosistema se mantengan saludables ysustentables.

Su sponsorship también demuestra un fuerte compromiso con lacomunidad de FastAPI (tú), mostrando que no solo les importa ofrecer ungran servicio, sino también apoyar unframework robusto y próspero, FastAPI. 🙇

Por ejemplo, podrías querer probar:

• Speakeasy
• Stainless
• liblab

Algunas de estas soluciones también pueden ser open source u ofrecer niveles gratuitos, así que puedes probarlas sin un compromiso financiero. Hay otros generadores de SDK comerciales disponibles y se pueden encontrar en línea. 🤓

Crea un SDK de TypeScript¶

Empecemos con una aplicación simple de FastAPI:

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strprice:floatclassResponseMessage(BaseModel):message:str@app.post("/items/",response_model=ResponseMessage)asyncdefcreate_item(item:Item):return{"message":"item received"}@app.get("/items/",response_model=list[Item])asyncdefget_items():return[{"name":"Plumbus","price":3},{"name":"Portal Gun","price":9001},]

Nota que laspath operations definen los modelos que usan para el payload del request y el payload del response, usando los modelosItem yResponseMessage.

Documentación de la API¶

Si vas a/docs, verás que tiene losesquemas para los datos a enviar en requests y recibir en responses:

Puedes ver esos esquemas porque fueron declarados con los modelos en la app.

Esa información está disponible en elOpenAPI schema de la app, y luego se muestra en la documentación de la API.

Y esa misma información de los modelos que está incluida en OpenAPI es lo que puede usarse paragenerar el código del cliente.

Hey API¶

Una 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.

npx@hey-api/openapi-ts-ihttp://localhost:8000/openapi.json-osrc/client

Esto generará un SDK de TypeScript en./src/client.

Puedes aprender cómoinstalar@hey-api/openapi-ts y leer sobre eloutput generado en su sitio web.

Usar el SDK¶

Ahora puedes importar y usar el código del cliente. Podría verse así, nota que tienes autocompletado para los métodos:

También obtendrás autocompletado para el payload a enviar:

Tendrás errores en línea para los datos que envíes:

El objeto de response también tendrá autocompletado:

App de FastAPI con tags¶

En muchos casos tu app de FastAPI será más grande, y probablemente usarás tags para separar diferentes grupos depath operations.

Por ejemplo, podrías tener una sección paraitems y otra sección parausers, y podrían estar separadas por tags:

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strprice:floatclassResponseMessage(BaseModel):message:strclassUser(BaseModel):username:stremail:str@app.post("/items/",response_model=ResponseMessage,tags=["items"])asyncdefcreate_item(item:Item):return{"message":"Item received"}@app.get("/items/",response_model=list[Item],tags=["items"])asyncdefget_items():return[{"name":"Plumbus","price":3},{"name":"Portal Gun","price":9001},]@app.post("/users/",response_model=ResponseMessage,tags=["users"])asyncdefcreate_user(user:User):return{"message":"User received"}

Genera un Cliente TypeScript con tags¶

Si generas un cliente para una app de FastAPI usando tags, normalmente también separará el código del cliente basándose en los tags.

De esta manera podrás tener las cosas ordenadas y agrupadas correctamente para el código del cliente:

En este caso tienes:

• ItemsService
• UsersService

Nombres de los métodos del cliente¶

Ahora mismo los nombres de los métodos generados comocreateItemItemsPost no se ven muy limpios:

ItemsService.createItemItemsPost({name:"Plumbus",price:5})

...eso es porque el generador del cliente usa eloperation ID interno de OpenAPI para cadapath operation.

OpenAPI requiere que cada operation ID sea único a través de todas laspath operations, por lo que FastAPI usa elnombre de la función, elpath, y elmétodo/operación HTTP para generar ese operation ID, porque de esa manera puede asegurarse de que los operation IDs sean únicos.

Pero te mostraré cómo mejorar eso a continuación. 🤓

Operation IDs personalizados y mejores nombres de métodos¶

Puedesmodificar la forma en que estos operation IDs songenerados para hacerlos más simples y tenernombres de métodos más simples en los clientes.

En este caso tendrás que asegurarte de que cada operation ID seaúnico de alguna otra manera.

Por ejemplo, podrías asegurarte de que cadapath operation tenga un tag, y luego generar el operation ID basado en eltag y elname de lapath operation (el nombre de la función).

Función personalizada para generar ID único¶

FastAPI usa unID único para cadapath operation, se usa para eloperation ID y también para los nombres de cualquier modelo personalizado necesario, para requests o responses.

Puedes personalizar esa función. Toma unAPIRoute y retorna un string.

Por ejemplo, aquí está usando el primer tag (probablemente tendrás solo un tag) y el nombre de lapath operation (el nombre de la función).

Puedes entonces pasar esa función personalizada aFastAPI como el parámetrogenerate_unique_id_function:

fromfastapiimportFastAPIfromfastapi.routingimportAPIRoutefrompydanticimportBaseModeldefcustom_generate_unique_id(route:APIRoute):returnf"{route.tags[0]}-{route.name}"app=FastAPI(generate_unique_id_function=custom_generate_unique_id)classItem(BaseModel):name:strprice:floatclassResponseMessage(BaseModel):message:strclassUser(BaseModel):username:stremail:str@app.post("/items/",response_model=ResponseMessage,tags=["items"])asyncdefcreate_item(item:Item):return{"message":"Item received"}@app.get("/items/",response_model=list[Item],tags=["items"])asyncdefget_items():return[{"name":"Plumbus","price":3},{"name":"Portal Gun","price":9001},]@app.post("/users/",response_model=ResponseMessage,tags=["users"])asyncdefcreate_user(user:User):return{"message":"User received"}

Genera un Cliente TypeScript con operation IDs personalizados¶

Ahora, si generas el cliente de nuevo, verás que tiene los nombres de métodos mejorados:

Como 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.

Preprocesa la especificación OpenAPI para el generador de clientes¶

El código generado aún tiene algo deinformación duplicada.

Ya sabemos que este método está relacionado con lositems porque esa palabra está en elItemsService (tomado del tag), pero aún tenemos el nombre del tag prefijado en el nombre del método también. 😕

Probablemente aún querremos mantenerlo para OpenAPI en general, ya que eso asegurará que los operation IDs seanúnicos.

Pero para el cliente generado podríamosmodificar los operation IDs de OpenAPI justo antes de generar los clientes, solo para hacer esos nombres de métodos más bonitos ylimpios.

Podríamos descargar el JSON de OpenAPI a un archivoopenapi.json y luego podríamosremover ese tag prefijado con un script como este:

importjsonfrompathlibimportPathfile_path=Path("./openapi.json")openapi_content=json.loads(file_path.read_text())forpath_datainopenapi_content["paths"].values():foroperationinpath_data.values():tag=operation["tags"][0]operation_id=operation["operationId"]to_remove=f"{tag}-"new_operation_id=operation_id[len(to_remove):]operation["operationId"]=new_operation_idfile_path.write_text(json.dumps(openapi_content))

import*asfsfrom'fs'asyncfunctionmodifyOpenAPIFile(filePath){try{constdata=awaitfs.promises.readFile(filePath)constopenapiContent=JSON.parse(data)constpaths=openapiContent.pathsfor(constpathKeyofObject.keys(paths)){constpathData=paths[pathKey]for(constmethodofObject.keys(pathData)){constoperation=pathData[method]if(operation.tags&&operation.tags.length>0){consttag=operation.tags[0]constoperationId=operation.operationIdconsttoRemove=`${tag}-`if(operationId.startsWith(toRemove)){constnewOperationId=operationId.substring(toRemove.length)operation.operationId=newOperationId}}}}awaitfs.promises.writeFile(filePath,JSON.stringify(openapiContent,null,2),)console.log('File successfully modified')}catch(err){console.error('Error:',err)}}constfilePath='./openapi.json'modifyOpenAPIFile(filePath)

Con eso, los operation IDs serían renombrados de cosas comoitems-get_items a sologet_items, de esa manera el generador del cliente puede generar nombres de métodos más simples.

Genera un Cliente TypeScript con el OpenAPI preprocesado¶

Como el resultado final ahora está en un archivoopenapi.json, necesitas actualizar la ubicación de la entrada:

npx@hey-api/openapi-ts-i./openapi.json-osrc/client

Después de generar el nuevo cliente, ahora tendrías nombres de métodoslimpios, con todo elautocompletado,errores en línea, etc:

Beneficios¶

Cuando uses los clientes generados automáticamente obtendrásautocompletado para:

• Métodos.
• Payloads de request en el body, parámetros de query, etc.
• Payloads de response.

También tendráserrores en línea para todo.

Y cada vez que actualices el código del backend, yregeneres el frontend, tendrás las nuevaspath operations disponibles como métodos, las antiguas eliminadas, y cualquier otro cambio se reflejará en el código generado. 🤓

Esto también significa que si algo cambió seráreflejado automáticamente en el código del cliente. Y si hacesbuild del cliente, dará error si tienes algúndesajuste en los datos utilizados.

Así 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. ✨