From a1f72bffb588aa9d6b4cce824074558e9c9df3f6 Mon Sep 17 00:00:00 2001 From: Biel Stela Date: Mon, 15 Jul 2024 18:47:51 +0200 Subject: [PATCH] tidyup api documentation --- api/app/models/grid.py | 33 +++++++++++++++++++-------------- api/app/routers/grid.py | 18 +++++++++--------- 2 files changed, 28 insertions(+), 23 deletions(-) diff --git a/api/app/models/grid.py b/api/app/models/grid.py index 47b74a58..1dee3260 100644 --- a/api/app/models/grid.py +++ b/api/app/models/grid.py @@ -44,12 +44,12 @@ class CategoricalLegend(BaseModel): class DatasetMeta(BaseModel): - var_name: str = Field(description="Column name") - var_dtype: str = Field(description="Column dtype. ") + var_name: str = Field(description="Column name.") + var_dtype: str = Field(description="Column dtype.") nodata: str description: str - aggregation_method: str = Field(description="Aggregation method used to compute the overview levels") - lineage: list[str] | None = Field(default=None, description="Source data used to compute this dataset") + aggregation_method: str = Field(description="Aggregation method used to compute the overview levels.") + lineage: list[str] | None = Field(default=None, description="Source data used to compute this dataset.") legend: CategoricalLegend | NumericalLegend = Field(discriminator="legend_type") @@ -60,8 +60,8 @@ class H3GridInfo(BaseModel): class MultiDatasetMeta(BaseModel): - datasets: list[DatasetMeta] = Field(description="Variables represented in this dataset") - h3_grid_info: list[H3GridInfo] = Field(description="H3 related information") + datasets: list[DatasetMeta] = Field(description="Variables represented in this dataset.") + h3_grid_info: list[H3GridInfo] = Field(description="H3 related information.") # =============================================== @@ -85,22 +85,27 @@ class CategoricalOperators(str, Enum): class CategoricalFilter(BaseModel): filter_type: Literal["categorical"] - column_name: str = Field(description="Name of the column to which the filter will apply") - operation: CategoricalOperators = Field() - value: list[int] = Field(description="Value to compare with") + column_name: str = Field(description="Name of the column to which the filter will apply.") + operation: CategoricalOperators + value: list[int] = Field(description="Value to compare with.") class NumericalFilter(BaseModel): filter_type: Literal["numerical"] - column_name: str = Field(description="Name of the column to which the filter will apply") - operation: NumericalOperators = Field(description="Operation to use in compare") - value: float = Field(description="Value to compare with") + column_name: str = Field(description="Name of the column to which the filter will apply.") + operation: NumericalOperators = Field(description="Operation to use in compare.") + value: float = Field(description="Value to compare with.") class TableFilters(BaseModel): filters: list[Annotated[CategoricalFilter | NumericalFilter, Field(discriminator="filter_type")]] - limit: int = Field(10, lt=1000, description="Number of records") - order_by: Annotated[list[str], Field(Query(..., description="Prepend '-' to column name to make it descending"))] + limit: int = Field(Query(10, lt=1000, description="Number of records.")) + order_by: Annotated[ + list[str], + Field( + Query(..., description="Prepend '-' to column name to make it descending"), + ), + ] def to_sql_query(self, table_name: str) -> str: """Compile model to sql query""" diff --git a/api/app/routers/grid.py b/api/app/routers/grid.py index 83468fd7..cf645b69 100644 --- a/api/app/routers/grid.py +++ b/api/app/routers/grid.py @@ -1,11 +1,11 @@ import logging import os -from pathlib import Path +import pathlib from typing import Annotated import h3 import polars as pl -from fastapi import APIRouter, Depends, HTTPException, Query +from fastapi import APIRouter, Depends, HTTPException, Path, Query from fastapi.responses import ORJSONResponse from h3 import H3CellError from pydantic import ValidationError @@ -21,16 +21,15 @@ @grid_router.get( "/tile/{tile_index}", - responses={200: {"description": "Get a grid tile"}, 404: {"description": "Not found"}}, - response_model=None, + summary="Get a grid tile", ) async def grid_tile( - tile_index: str, + tile_index: Annotated[str, Path(description="The `h3` index of the tile")], columns: list[str] = Query( - [], description="Colum/s to include in the tile. If empty, it returns only the cell index." + [], description="Colum/s to include in the tile. If empty, it returns only cell indexes." ), ) -> Response: - """Request a tile of h3 cells filtered by columns""" + """Get a tile of h3 cells with specified data columns""" try: z = h3.api.basic_str.h3_get_resolution(tile_index) except H3CellError: @@ -47,9 +46,10 @@ async def grid_tile( @grid_router.get( "/meta", + summary="Dataset metadata", ) async def grid_dataset_metadata() -> MultiDatasetMeta: - """Dataset metadata""" + """Get the grid dataset metadata""" file = os.path.join(get_settings().grid_tiles_path, "meta.json") with open(file) as f: raw = f.read() @@ -69,7 +69,7 @@ def read_table( filters: TableFilters = Depends(), ) -> ORJSONResponse: """Query tile dataset and return table data""" - files_path = Path(get_settings().grid_tiles_path) / str(level) + files_path = pathlib.Path(get_settings().grid_tiles_path) / str(level) if not files_path.exists(): raise HTTPException(404, detail=f"Level {level} does not exist") from None lf = pl.scan_ipc(files_path.glob("*.arrow"))