Si vous n'êtes pas un "expert" en OpenAPI, vous n'en avez probablement pas besoin.
Dans OpenAPI, les chemins sont des ressources, tels que /users/ ou /items/, exposées par votre API, et les opérations sont les méthodes HTTP utilisées pour manipuler ces chemins, telles que GET, POST ou DELETE. Les operationId sont des chaînes uniques facultatives utilisées pour identifier une opération d'un chemin. Vous pouvez définir l'OpenAPI operationId à utiliser dans votre opération de chemin avec le paramètre operation_id.
Vous devez vous assurer qu'il est unique pour chaque opération.
Utilisation du nom path operation function comme operationId¶
Si vous souhaitez utiliser les noms de fonction de vos API comme operationId, vous pouvez les parcourir tous et remplacer chaque operation_id de l'opération de chemin en utilisant leur APIRoute.name.
Vous devriez le faire après avoir ajouté toutes vos paramètres de chemin.
fromfastapiimportFastAPIfromfastapi.routingimportAPIRouteapp=FastAPI()@app.get("/items/")asyncdefread_items():return[{"item_id":"Foo"}]defuse_route_names_as_operation_ids(app:FastAPI)->None:""" Simplify operation IDs so that generated API clients have simpler function names. Should be called only after all routes have been added. """forrouteinapp.routes:ifisinstance(route,APIRoute):route.operation_id=route.name# in this case, 'read_items'use_route_names_as_operation_ids(app)
Astuce
Si vous appelez manuellement app.openapi(), vous devez mettre à jour les operationId avant.
Attention
Pour faire cela, vous devez vous assurer que chacun de vos chemin ait un nom unique.
Même s'ils se trouvent dans des modules différents (fichiers Python).
Pour exclure un chemin du schéma OpenAPI généré (et donc des systèmes de documentation automatiques), utilisez le paramètre include_in_schema et assignez-lui la valeur False :
Vous pouvez limiter le texte utilisé de la docstring d'une fonction de chemin qui sera affiché sur OpenAPI.
L'ajout d'un \f (un caractère d'échappement "form feed") va permettre à FastAPI de tronquer la sortie utilisée pour OpenAPI à ce stade.
Il n'apparaîtra pas dans la documentation, mais d'autres outils (tel que Sphinx) pourront utiliser le reste.
fromtypingimportSet,UnionfromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:Union[str,None]=Noneprice:floattax:Union[float,None]=Nonetags:Set[str]=set()@app.post("/items/",response_model=Item,summary="Create an item")asyncdefcreate_item(item:Item):""" Create an item with all the information: - **name**: each item must have a name - **description**: a long description - **price**: required - **tax**: if the item doesn't have tax, you can omit this - **tags**: a set of unique tag strings for this item \f :param item: User input. """returnitem
Lorsque vous déclarez un chemin dans votre application, FastAPI génère automatiquement les métadonnées concernant ce chemin à inclure dans le schéma OpenAPI.
Détails techniques
La spécification OpenAPI appelle ces métadonnées des Objets d'opération.
Il contient toutes les informations sur le chemin et est utilisé pour générer automatiquement la documentation.
Il inclut les tags, parameters, requestBody, responses, etc.
Ce schéma OpenAPI spécifique aux operations est normalement généré automatiquement par FastAPI, mais vous pouvez également l'étendre.
Astuce
Si vous avez seulement besoin de déclarer des réponses supplémentaires, un moyen plus pratique de le faire est d'utiliser les réponses supplémentaires dans OpenAPI.
Vous pouvez étendre le schéma OpenAPI pour une opération de chemin en utilisant le paramètre openapi_extra.
Personnalisation du Schéma OpenAPI pour un chemin¶
Le dictionnaire contenu dans la variable openapi_extra sera fusionné avec le schéma OpenAPI généré automatiquement pour l'opération de chemin.
Ainsi, vous pouvez ajouter des données supplémentaires au schéma généré automatiquement.
Par exemple, vous pouvez décider de lire et de valider la requête avec votre propre code, sans utiliser les fonctionnalités automatiques de validation proposée par Pydantic, mais vous pouvez toujours définir la requête dans le schéma OpenAPI.
Vous pouvez le faire avec openapi_extra :
fromfastapiimportFastAPI,Requestapp=FastAPI()defmagic_data_reader(raw_body:bytes):return{"size":len(raw_body),"content":{"name":"Maaaagic","price":42,"description":"Just kiddin', no magic here. ✨",},}@app.post("/items/",openapi_extra={"requestBody":{"content":{"application/json":{"schema":{"required":["name","price"],"type":"object","properties":{"name":{"type":"string"},"price":{"type":"number"},"description":{"type":"string"},},}}},"required":True,},},)asyncdefcreate_item(request:Request):raw_body=awaitrequest.body()data=magic_data_reader(raw_body)returndata
Dans cet exemple, nous n'avons déclaré aucun modèle Pydantic. En fait, le corps de la requête n'est même pas parsé en tant que JSON, il est lu directement en tant que bytes, et la fonction magic_data_reader() serait chargé de l'analyser d'une manière ou d'une autre.
Néanmoins, nous pouvons déclarer le schéma attendu pour le corps de la requête.
En utilisant cette même astuce, vous pouvez utiliser un modèle Pydantic pour définir le schéma JSON qui est ensuite inclus dans la section de schéma OpenAPI personnalisée pour le chemin concerné.
Et vous pouvez le faire même si le type de données dans la requête n'est pas au format JSON.
Dans cet exemple, nous n'utilisons pas les fonctionnalités de FastAPI pour extraire le schéma JSON des modèles Pydantic ni la validation automatique pour JSON. En fait, nous déclarons le type de contenu de la requête en tant que YAML, et non JSON :
Néanmoins, bien que nous n'utilisions pas la fonctionnalité par défaut, nous utilisons toujours un modèle Pydantic pour générer manuellement le schéma JSON pour les données que nous souhaitons recevoir en YAML.
Ensuite, nous utilisons directement la requête et extrayons son contenu en tant qu'octets. Cela signifie que FastAPI n'essaiera même pas d'analyser le payload de la requête en tant que JSON.
Et nous analysons directement ce contenu YAML, puis nous utilisons à nouveau le même modèle Pydantic pour valider le contenu YAML :