Validez votre schéma OpenAPI face aux standards REST Belgif

Construire des API est relativement facile, mais construire des API conformes et interopérables est un tout autre défi. Si vous travaillez sur des projets pour le gouvernement belge ou le secteur public, vous avez probablement déjà croisé les standards REST Belgif. Ces directives complètes garantissent que les API des différentes institutions restent cohérentes, prévisibles et faciles à consommer.

Les frameworks modernes comme FastAPI sont excellents pour construire rapidement des API et générer automatiquement la documentation OpenAPI, mais leur génération de schéma par défaut ne colle pas toujours parfaitement aux règles de linting strictes de Belgif.

Dans cet article, nous allons voir comment utiliser le linter OpenAPI officiel de Belgif via Docker et comment valider votre application FastAPI face à quelques erreurs potentielles. Plus important encore, nous allons parcourir des solutions pratiques, pas à pas, pour résoudre les erreurs de linting les plus courantes causées par les comportements par défaut de FastAPI, afin que votre API obtienne un certificat de bonne santé.

Avant d'entrer dans le vif du sujet, si vous cherchez des conseils généraux sur la conception d'API robustes, jetez un œil à mon article précédent : API REST - Comment écrire de bonnes API.

Le linter en action​

Une fois le container belgif-lint en place (voir la section Installation ci-dessous), vérifier un fichier openapi.json tient en deux commandes :

$ curl -s http://localhost:8000/openapi.json > openapi.json
▋

$ docker compose run --rm belgif-lint▋

Cela produira quelque chose comme ceci :

[INFO] Scanning for projects...
[INFO]
[INFO] ------------------< org.apache.maven:standalone-pom >-------------------?
[INFO] Building Maven Stub Project (No POM) 1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] --- belgif-rest-guide-validator:3.1.0:validate-openapi (default-cli) @ standalone-pom ---?
[INFO] Validating following files:[/app/openapi.json]?
[INFO] Found kmodule: jar:file:/root/.m2/repository/io/github/belgif/rest/guide/validator/belgif-rest-guide-validator-rules/3.1.0/belgif-rest-guide-validator-rules-3.1.0.jar!/META-INF/kmodule.xml?
[INFO] Creating KieModule for artifact io.github.belgif.rest.guide.validator:belgif-rest-guide-validator-rules:3.1.0?
[INFO] Artifact io.github.belgif.rest.guide.validator:belgif-rest-guide-validator-rules:3.1.0 has executable model?
[INFO] Start creation of KieBase: defaultKieBase?
[...]

OpenApi validation summary: 30 violations and 0 ignored violations.?
[MANDATORY]    [err-problem] Each error response of each operation SHOULD have a media type "application/problem+json" 2 occurrences:?
openapi.json    ln   1  #/paths/items/{item_id}/get/responses/422 -- [Operation: GET /items/{item_id}]?
openapi.json    ln   1  #/paths/items//get/responses/422 -- [Operation: GET /items/]
[MANDATORY]    [evo-object] In a request or response body, if any, you MUST always return a JSON object (and not e.g. an array) as a top level data structure to support future extensibility.  5 occurrences:
openapi.json    ln   1  #/paths//get/responses/200/content/application/json
openapi.json    ln   1  #/paths/items//get/responses/200/content/application/json
openapi.json    ln   1  #/paths/items/{item_id}/get/responses/200/content/application/json
openapi.json    ln   1  #/paths/items/{item_id}/get/responses/422/content/application/json
openapi.json    ln   1  #/paths/items//get/responses/422/content/application/json
[MANDATORY]    [oas-comp]   Component names SHOULD use UpperCamelCase notation. For abbreviations as well, all letters except the first one should be lowercased. 1 occurrence:
openapi.json    ln   1  #/components/schemas/HTTPValidationError
[MANDATORY]    [oas-contra] OpenAPI 3.1 improves upon OpenAPI 3.0, but to avoid interoperability problems it SHOULD NOT be used yet because it is not yet widely supported by most tooling. 1 occurrence:
#
[MANDATORY]    [oas-descr]  The title property of a Schema MUST NOT be used. 10 occurrences:
openapi.json    ln   1  #/paths/items//get/parameters/0/schema
openapi.json    ln   1  #/components/schemas/ValidationError/properties/msg
openapi.json    ln   1  #/components/schemas/HTTPValidationError
openapi.json    ln   1  #/components/schemas/ValidationError/properties/type
openapi.json    ln   1  #/paths/items/{item_id}/get/parameters/1/schema
openapi.json    ln   1  #/components/schemas/ValidationError/properties/loc
openapi.json    ln   1  #/paths/items/{item_id}/get/parameters/0/schema
openapi.json    ln   1  #/components/schemas/ValidationError
openapi.json    ln   1  #/paths/items//get/parameters/1/schema
openapi.json    ln   1  #/components/schemas/HTTPValidationError/properties/detail
[MANDATORY]    [openapi-opid] A unique operationId MUST be specified on each operation. It SHOULD have a lowerCamelCase value following common programming naming conventions for method (function) names. 3 occurrences:?
openapi.json    ln   1  #/paths/items//get -- OperationId not lowerCamelCase: read_items_items__get
openapi.json    ln   1  #/paths//get -- OperationId not lowerCamelCase: read_root__get
openapi.json    ln   1  #/paths/items/{item_id}/get -- OperationId not lowerCamelCase: read_item_items__item_id__get
[MANDATORY]    [path-param] Path parameters SHOULD use lowerCamelCase notation. 1 occurrence:
openapi.json    ln   1  #/paths/items/{item_id}/get/parameters/0
[MANDATORY]    [prb-defaul] A default Problem response SHOULD be added to each operation with media type "application/problem+json" 3 occurrences:
openapi.json    ln   1  #/paths/items/{item_id}/get -- [Operation: GET /items/{item_id}]
openapi.json    ln   1  #/paths/items//get -- [Operation: GET /items/]
openapi.json    ln   1  #/paths//get -- [Operation: GET /]
[MANDATORY]    [uri-format] The server url should follow the format [/pathPrefix]/apiName/vMajorVersion optionally prefixed by https://hostname[:port] or http://localhost[:port]. The apiName must consist of one or more path segments in lowerCamelCase. 1 occurrence:
#/servers/0
[MANDATORY]    [uri-notat]  Trailing slashes MUST NOT be used. 2 occurrences:
openapi.json    ln   1  #/paths/
openapi.json    ln   1  #/paths/items/
[RECOMMENDED]  [hlth-res]   Each REST API SHOULD expose a GET /health operation which returns the availability of the API’s functionality for its clients. 1 occurrence:
openapi.json    ln   1  #/paths
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[...]

[WARNING] In an eval expression [ApiFunctions.existsPathWithPathParamAfter($path.getIdentifier(), parserResult)] : '$path' comes from previous pattern 'PathDefinition'. 'parserResult' comes from previous pattern 'Parser$ParserResult'. Consider placing the constraint in the pattern and removing the eval if possible, as eval is not performance-efficient.?
[WARNING] In an eval expression [ApiFunctions.isMediaTypeIncluded($contentType, Set.of("application/json"))] : '$contentType' comes from previous pattern 'String'. Consider placing the constraint in the pattern and removing the eval if possible, as eval is not performance-efficient.?
[WARNING] In an eval expression [isObjectType($responseSchema, parserResult)] : '$responseSchema' comes from previous pattern 'Schema'. 'parserResult' comes from previous pattern 'Parser$ParserResult'. Consider placing the constraint in the pattern and removing the eval if possible, as eval is not performance-efficient.?
[WARNING] In an eval expression [!hasItemsArray($responseSchema, parserResult)] : '$responseSchema' comes from previous pattern 'Schema'. 'parserResult' comes from previous pattern 'Parser$ParserResult'. Consider placing the constraint in the pattern and removing the eval if possible, as eval is not performance-efficient.
[WARNING] In an eval expression [ApiFunctions.existsPathWithPathParamAfter($path.getIdentifier(), parserResult)] : '$path' comes from previous pattern 'PathDefinition'. 'parserResult' comes from previous pattern 'Parser$ParserResult'. Consider placing the constraint in the pattern and removing the eval if possible, as eval is not performance-efficient.
[WARNING] In an eval expression [ApiFunctions.isMediaTypeIncluded($contentType, Set.of("application/json"))] : '$contentType' comes from previous pattern 'String'. Consider placing the constraint in the pattern and removing the eval if possible, as eval is not performance-efficient.
[WARNING] In an eval expression [isObjectType($responseSchema, parserResult)] : '$responseSchema' comes from previous pattern 'Schema'. 'parserResult' comes from previous pattern 'Parser$ParserResult'. Consider placing the constraint in the pattern and removing the eval if possible, as eval is not performance-efficient.
[WARNING] In an eval expression [hasItemsArray($responseSchema, parserResult)] : '$responseSchema' comes from previous pattern 'Schema'. 'parserResult' comes from previous pattern 'Parser$ParserResult'. Consider placing the constraint in the pattern and removing the eval if possible, as eval is not performance-efficient.
[WARNING] In an eval expression [!hasCollectionResponse($responseSchema, parserResult)] : '$responseSchema' comes from previous pattern 'Schema'. 'parserResult' comes from previous pattern 'Parser$ParserResult'. Consider placing the constraint in the pattern and removing the eval if possible, as eval is not performance-efficient.
[WARNING] In an eval expression [$schema != null] : '$schema' comes from previous pattern 'Schema'. Consider placing the constraint in the pattern and removing the eval if possible, as eval is not performance-efficient.?
[WARNING] More eval warnings will be suppressed...?
[WARNING] No correct line number found for: /servers/0?

services:
  app:
    build: .
    ports:
      - "8000:80"?
    volumes:
      - ./main.py:/code/main.py?

  # Belgif Validator Service
  belgif-lint:
    image: maven:3.9.9-eclipse-temurin-17-alpine
    volumes:
      - .:/app:ro
      - maven-cache:/root/.m2?
    working_dir: /app
    # 1. We override the entrypoint to use a shell (required for pipes)
    entrypoint: ["/bin/sh", "-c"]?
    # 2. We use 'set +e' to not close the terminal if an error is met
    #    Use style.color=always to keep ANSI colors while piping output to grep
    #    Use 2>&1 to merge STDERR and STDOUT so line ordering is kept during the pipe
    command: >?
      "set +e &&
      mvn \
      io.github.belgif.rest.guide.validator:belgif-rest-guide-validator-maven-plugin:3.1.0:validate-openapi \
      -Dstyle.color=always \
      -Drest-guide-validator.files=openapi.json \
      -Drest-guide-validator.outputTypes=CONSOLE \
      2>&1 \?
      | grep -v 'eval expression' \
      | grep -v 'More eval warnings will be suppressed' \
      | grep -v 'comes from previous pattern' \
      | grep -v 'No correct line number'"


volumes:
  maven-cache:

Les standards Belgif​

Les standards REST Belgif sont définis sur https://www.belgif.be/specification/rest/api-guide/ et constituent un effort collaboratif de plusieurs institutions gouvernementales belges, à l'origine sous l'égide du G-Cloud, avant de passer chez Belgif, le Belgian Interoperability Framework. Son objectif est d'améliorer la compatibilité entre les services RESTful proposés par les institutions publiques ou toute autre organisation adoptant ces directives.

Si vous voulez vérifier si votre API est conforme, vous pouvez utiliser le belgif-rest-guide-validator comme documenté dans la section Tools.

Installation — Créer une application bidon​

Si vous n'en avez pas encore, cliquez simplement sur Generate install script ci-dessous et collez la ligne de commande dans un terminal, puis appuyez sur la touche Enter pour créer la structure du projet dans un dossier /tmp/fastapi sur votre disque.

Le code de main.py définit :

• Un endpoint racine / qui retourne un simple JSON.
• Un endpoint /items/{item_id} qui accepte un entier item_id comme paramètre de path et un paramètre de query optionnel q de type chaîne.
• Un endpoint /items/ qui accepte les paramètres de query skip et limit pour la pagination.

Pour le lancer, exécutez simplement docker compose up --build -d dans votre terminal :

$ docker compose up --build -d▋

Rendez-vous ensuite sur http://localhost:8000/docs pour voir votre application tourner.

Vous pouvez la tester avec curl ou votre navigateur :

1. Endpoint racine :

   user@machine: ~/yourproject

   $ curl http://localhost:8000
   ▋

   Vous devriez voir : {"Hello":"World"}

2. Item avec paramètre de path et de query :

   user@machine: ~/yourproject

   $ curl "http://localhost:8000/items/5?q=somequery"
   ▋

   Vous devriez voir : {"item_id":5,"q":"somequery"}

3. Items avec pagination :

   user@machine: ~/yourproject

   $ curl "http://localhost:8000/items/?skip=0&limit=20"
   ▋

   Vous devriez voir : {"skip":0,"limit":20}

Ajouter le linter Belgif​

Le plus simple est d'utiliser un container Docker. Dans l'exemple de code ci-dessous, regardez la nouvelle version de compose.yaml : nous avons ajouté un service belgif-lint basé sur maven.

Une fois que vous avez relancé docker compose up --build -d pour créer le container belgif-lint, vous êtes prêt à lancer la vérification montrée en début d'article — il vous faut juste d'abord un fichier openapi.json sur le disque, ce que produit exactement la première commande là-haut.

Astuces FastAPI​

oas-tags - Gérer les tags​

Vous obtiendrez l'erreur [MANDATORY] [oas-tags] Each tag used on an operation SHOULD also be declared in the top level tags list of the OpenAPI document, with an optional description. lorsque vous utilisez un ou plusieurs tags dans vos endpoints et que ces tags ne sont pas déclarés.

Pour résoudre ça, vous devez utiliser l'attribut openapi_tags comme illustré ci-dessous :

# Define the metadata for your tags
tags_metadata: list[dict[str, str]] = [?
    {
        "name": "Retrieving data",
        "description": "Operations related to fetching and querying data.",
    },
    {
        "name": "Healthcheck",
        "description": "Endpoints to monitor the health status of the application.",
    },
]

app = FastAPI(
    # ...
    openapi_tags=tags_metadata,  # belgif [oas-tags]?
    # ...
)

oas-contra - N'utilisez pas encore OpenAPI 3.1​

Si vous obtenez [MANDATORY] [oas-contra] OpenAPI 3.1 improves upon OpenAPI 3.0, but to avoid interoperability problems it SHOULD NOT be used yet because it is not yet widely supported by most tooling., vous pouvez régler cette erreur en rétrogradant la version d'OpenAPI utilisée par FastAPI comme ceci :

app = FastAPI(
    # ...
    openapi_version="3.0.2", # belgif [oas-contra]
)

oas-descr - La propriété title doit être supprimée​

Vous obtiendrez [MANDATORY] [oas-descr] The title property of a Schema MUST NOT be used. quand FastAPI génère à la fois une propriété title et une propriété description pour vos objets.

La solution est d'ajouter une fonction utilitaire et de supprimer le title (puisque description est toujours généré) :

Code partiel :

if "components" in openapi_schema and "schemas" in openapi_schema["components"]:
    for schema in openapi_schema["components"]["schemas"].values():
        _remove_titles(schema)

Voir l'utilitaire fourni plus loin dans l'article.

oas-comp - Les noms de composants doivent utiliser la notation UpperCamelCase​

Si vous obtenez l'erreur [MANDATORY] [oas-comp] Component names SHOULD use UpperCamelCase notation. For abbreviations as well, all letters except the first one should be lowercased., vous devrez ajouter une fonction de renommage pour transformer par exemple HTTPValidationError en HttpValidationError.

Cela peut se faire par exemple comme ceci (code partiel) :

def _fix_schema_names(openapi_schema: dict[str, Any]) -> None:
    """
    Renames schemas that violate Belgif's naming conventions.

    Specifically targets 'HTTPValidationError' (abbreviations must be camel-cased
    like 'Http', not 'HTTP').
    """
    components: Any = openapi_schema.get("components", {})
    schemas: Any = components.get("schemas", {})

    # Fix: HTTPValidationError -> HttpValidationError
    if "HTTPValidationError" in schemas:
        # 1. Move the definition to the new key
        schemas["HttpValidationError"] = schemas.pop("HTTPValidationError")

        # 2. Update all references ($ref) in the entire document to point to the new key
        _update_refs(
            openapi_schema, "#/components/schemas/HTTPValidationError", "#/components/schemas/HttpValidationError"
        )

Voir l'utilitaire fourni plus loin dans l'article.

openapi-opid - lowerCamelCase pour operationId​

Le message [MANDATORY] [openapi-opid] A unique operationId MUST be specified on each operation. It SHOULD have a lowerCamelCase value following common programming naming conventions for method (function) names. vous signale l'utilisation d'une mauvaise syntaxe.

Code partiel :

def _fix_operation_ids(openapi_schema: dict[str, Any]) -> None:
    """
    Iterates over all paths and converts snake_case operationIds to camelCase.
    """
    paths: Any = openapi_schema.get("paths", {})

    for path_item in paths.values():
        for operation in path_item.values():
            if isinstance(operation, dict) and "operationId" in operation:
                old_id: str = cast(str, operation["operationId"])
                operation["operationId"] = _to_camel_case(old_id)

L'utilitaire openapi.py​

L'utilitaire fourni ci-dessous peut vous aider à résoudre les erreurs oas-descr et oas-comp.

Le fichier main.py montre comment appeler cet utilitaire.

from helpers.openapi import configure_custom_openapi?

# Your code...

app = FastAPI(?
    # ...
)

# Call the helper and pass the FastAPI object

configure_custom_openapi(app)?

"""
OpenAPI Configuration Helper.

This module isolates the logic required to customize the generated OpenAPI (Swagger)
schema (i.e. the "openapi.json" file).

It specifically handles:
1. Removal of redundant 'title' fields (Rule: oas-descr).
2. Renaming schemas to strict CamelCase (e.g. HTTPValidationError -> HttpValidationError).
3. Converting Operation IDs to camelCase (Rule: openapi-opid).

This allows 'main.py' to remain clean while satisfying strict linters like Belgif.
"""

import re
from typing import Any, cast

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

# Define a recursive type for JSON schemas to fix strict typing issues.
JsonNode = dict[str, Any] | list[Any] | Any?


def _remove_titles(schema: Any) -> None:
    """
    Recursively removes the 'title' key from a JSON-like schema dictionary.
    """
    if isinstance(schema, dict):
        # Explicit cast to silence linter warnings about unknown keys
        s_dict: dict[str, Any] = cast(dict[str, Any], schema)?

        s_dict.pop("title", None)?

        for value in s_dict.values():
            _remove_titles(value)

    elif isinstance(schema, list):
        for item in schema:
            _remove_titles(item)


def _to_camel_case(snake_str: str) -> str:
    """Converts snake_case to lowerCamelCase."""
    components: list[str] = snake_str.split("_")
    # We capitalize the first letter of each component except the first one
    return components[0] + "".join(x.title() for x in components[1:])?


def _update_refs(item: Any, old_ref: str, new_ref: str) -> None:
    """
    Recursively updates $ref strings in the schema.

    Used when a schema component is renamed.
    """
    if isinstance(item, dict):
        s_dict: dict[str, Any] = cast(dict[str, Any], item)

        # If this node is a reference to the old name, update it
        if s_dict.get("$ref") == old_ref:?
            s_dict["$ref"] = new_ref
            return

        for value in s_dict.values():
            _update_refs(value, old_ref, new_ref)

    elif isinstance(item, list):
        for sub_item in item:
            _update_refs(sub_item, old_ref, new_ref)


def _fix_schema_names(openapi_schema: dict[str, Any]) -> None:
    """
    Renames schemas that violate Belgif's naming conventions.

    Specifically targets 'HTTPValidationError' (abbreviations must be camel-cased
    like 'Http', not 'HTTP').
    """
    components: Any = openapi_schema.get("components", {})
    schemas: Any = components.get("schemas", {})

    # Fix: HTTPValidationError -> HttpValidationError
    if "HTTPValidationError" in schemas:
        # 1. Move the definition to the new key
        schemas["HttpValidationError"] = schemas.pop("HTTPValidationError")?

        # 2. Update all references ($ref) in the entire document to point to the new key
        _update_refs(
            openapi_schema, "#/components/schemas/HTTPValidationError", "#/components/schemas/HttpValidationError"
        )


def _fix_operation_ids(openapi_schema: dict[str, Any]) -> None:
    """
    Iterates over all paths and converts snake_case operationIds to camelCase.
    """
    paths: Any = openapi_schema.get("paths", {})

    for path_item in paths.values():
        for operation in path_item.values():
            if isinstance(operation, dict) and "operationId" in operation:
                old_id: str = cast(str, operation["operationId"])?
                operation["operationId"] = _to_camel_case(old_id)


def configure_custom_openapi(app: FastAPI) -> None:
    """
    Overrides the default OpenAPI generator to apply Belgif compliance fixes.

    Args:
        app: The FastAPI application instance to configure.
    """

    def custom_openapi() -> dict[str, Any]:?
        if app.openapi_schema:?
            return app.openapi_schema

        # 1. Generate the default OpenAPI schema
        openapi_schema: dict[str, Any] = get_openapi(
            title=app.title,
            version=app.version,
            description=app.description,
            openapi_version=app.openapi_version,
            routes=app.routes,
            tags=app.openapi_tags,
        )

        # 2. Fix 1: Remove Titles (Clutter reduction) (belgif [oas-descr])
        if "components" in openapi_schema and "schemas" in openapi_schema["components"]:
            for schema in openapi_schema["components"]["schemas"].values():
                _remove_titles(schema)

        # 3. Fix 2: Rename Schemas (Naming conventions) (belgif [oas-comp])
        _fix_schema_names(openapi_schema)

        # 4. Fix 3: Operation IDs (snake_case -> camelCase) (belgif [openapi-opid])
        _fix_operation_ids(openapi_schema)

        app.openapi_schema = openapi_schema
        return app.openapi_schema

    # Assign the custom function to the app instance
    app.openapi = custom_openapi  # type: ignore[method-assign]?

Conclusion​

FastAPI vous offre gratuitement un schéma OpenAPI fonctionnel, mais « fonctionnel » et « conforme Belgif » sont deux niveaux d'exigence différents — le linter ci-dessus est ce qui comble l'écart, et les corrections de cet article couvrent les violations que les réglages par défaut de FastAPI déclenchent le plus souvent (les tags, la version d'OpenAPI, les propriétés title, les conventions de nommage). Lancez belgif-lint avant de livrer, pas après qu'un relecteur l'ait signalé.

Si vous êtes encore en train de concevoir l'API elle-même plutôt que de la valider, API REST - Comment écrire de bonnes API est l'article à lire en premier.