Improve the API documentation of end points

[laurent-laporte-pro]

Problem Statement

As a user of the Swagger API of the Antares Web application, I would like to have a detailed entry point documentation and to have usage examples in order to find more easily the functions I need to use the application.

Proposed Solution

The end points can be documented as follow:

• Add a description to each function from the user's point of view (docstring).
• Describe the path parameters using fastapi.param_functions.Path.
• Describe the query string parameters using fastapi.param_functions.Query.
• Describe the body parameters using fastapi.param_functions.Body.

If a parameter is mandatory, the default value will be ... (ellipses).

Developer Notes

• Consult the Metadata and Docs URLs documentation and Body - Multiple Parameters.

[laurent-laporte-pro]

Extensive example of end point documentation:

@bp.post(
    "/studies/{uuid}/commands",
    tags=[APITag.study_variant_management],
    summary="Append commands to a variant study or apply commands to a raw study",
    responses={
        status.HTTP_200_OK: {
            "description": (
                "List containing the command identifier(s)"
                "appended to the study variant, otherwise null"
            ),
        }
    },
)
def append_commands(
    uuid: str,
    commands: List[CommandDTO] = Body(
        ...,
        description="one or more commands to append or apply",
        examples={
            "Create an area": {
                "summary": "Create a new area in the study",
                "description": textwrap.dedent(
                    """
                    - `area_name`: area name, e.g.: "NORTH"
                    """
                ),
                "value": [
                    {
                        "action": "create_area",
                        "args": {"area_name": "NORTH"},
                    }
                ],
            },
            "Remove a cluster": {
                "summary": "Remove a cluster from an area",
                "description": textwrap.dedent(
                    """
                    - `area_id`: area identifier, e.g.: "north"
                    - `cluster_id`: cluster identifier, e.g.: "my_cluster"
                    """
                ),
                "value": [
                    {
                        "action": "remove_cluster",
                        "args": {
                            "area_id": "north",
                            "cluster_id": "my_cluster",
                        },
                    }
                ],
            },
        },
    ),
    current_user: JWTUser = Depends(auth.get_current_user),
) -> Optional[List[str]]:
    """
    Allow you to add one or more commands to a study variant or to modify a raw study.
    Modifications are applied immediately if the study is a raw study.

    - `uuid`: the study UUID to modify.
    - `commands`: List of commands to append or apply.
    """
    logger.info(
        f"Appending new command to variant study {uuid}",
        extra={"user": current_user.id},
    )
    params = RequestParameters(user=current_user)
    sanitized_uuid = sanitize_uuid(uuid)
    return study_service.apply_commands(sanitized_uuid, commands, params)