Reprise en main de la documentation API (Swagger) (#3351)

* Change case to reflect current branding * Improve description * Fix AOM API schema (#3350) * Run mix format * Fix community_resources.updated * Fix more datasets spec * Update schemas.ex * Fix format * Add assert_schema on datasets list operation * Fix /api/datasets specification We now properly report the response to be an array of Datasets, instead of a single Dataset. * Rename operation response (unsure of the impact) * Update documentation for datasets operation * Add more assert_schema * Achieve more assert schemas * Fix Dialyzer issues (#3397) * Fix credo warning * Add missing data required for API output See: - #3396 - #3399 * Make .aom.siren officially nullable See: - #3396 This will fix tests and make sure to reflect the actual production data. * Group operations together on the swagger UI * Update doc to reflect reality * Add TODO * Add one aom test at least * Fix test * Fix & modernize AOM specs (#3401) * Start fixing Resource & CommunityResource specs * Fix Autocomplete spec & add assert_schema * Start fixing Dataset spec * Update stats_controller_test.exs * Add notes about conversions * Add TODO * Remove unused import * Add TODO * Add req in dev for scripting Required because I now run some scripts with `mix run` to get the full app env. * Format * Create .gitignore * Format * Remove sometimes unseen field to reflect API behaviour * Format * Format * Format * Add missing schema_version * Format * Format * Temporary allow community resources here (#3407) * Start fixing CoveredArea (just country case for now) * Save WIP script used to validate current production data against local OpenAPI spec * Remove TODO * Add CoveredArea.Region and CoveredArea.AOM * Advertise behaviour #3408 * Add CoveredArea.Cities * Enforce type value for covered areas * Enforce type field value for Region * Remove bogus property * Format * Fix broken cities schema * Refactor dataset spec Improvements: - extract spec so that history is not allowed in the summarized view - make all keys required with an opt-out option * Emphasize this specific response is summarized a bit * Remove all "nullable: false" (since this is the default) * Introduce summarized vs detailed Resource * Improve GeoJSON / NeTEx checks * Set properties for community & regular resources * Format * Remove todo (won't do that) * Fix optional properties * Download all the datasets JSON * Improve dataset details spec * Remove TODO * Verify Resource properties * Allow direct "./scripts/api/spec_check.exs" invoke from shell * Increase timeout * Refactor tests for clarity * Disable highlight to fix SwaggerUI hanging in browser on large payloads (#3421) * Add note about SwaggerUI version See open-api-spex/open_api_spex#559 * Add useful links * Mix format * Add obsolete note * Fix wording * Remove comment which applies everywhere * Require all by default * Improve factories for required data (for tests to pass) Related: - #3399 * Improve wording * Fix broken specs * Fix broken specs * Fix broken assertion * Fix broken spec * Add extra assert_schema * Apply routing related match error fix * Enforce additionalProperties: false for all detected schemas with type object * Run mix format * DRY optional keys & remove TODO * Fix credo warning * Fix credo warning * Fix credo warning * Fix typo * Start verifying feature collections * Allow extra property for GeometryBase * Remove unused import * Fix (I think) Polygon to make tests pass * Move id to the right place * Add missing type * DRY things a bit * Add quiet TODO * Add note * Remove TODO (this is not correct) * Add note * Specify history & remove TODO * Remove TODO (will put it in the description of the PR) * Fix incorrect note * Fix broken link * Add note * Update schemas.ex * Mix format * Improve texts * Mix format * Update apps/transport/lib/transport_web/api/controllers/places_controller.ex Co-authored-by: Antoine Augusti <antoine.augusti@transport.data.gouv.fr> * Update apps/transport/lib/transport_web/api/schemas.ex Co-authored-by: Antoine Augusti <antoine.augusti@transport.data.gouv.fr> * Update apps/transport/lib/transport_web/api/schemas.ex Co-authored-by: Antoine Augusti <antoine.augusti@transport.data.gouv.fr> * Update apps/transport/test/support/factory.ex Co-authored-by: Antoine Augusti <antoine.augusti@transport.data.gouv.fr> * Update apps/transport/test/transport_web/controllers/api/schemas_test.exs Co-authored-by: Antoine Augusti <antoine.augusti@transport.data.gouv.fr> * Update apps/transport/test/transport_web/controllers/api/schemas_test.exs Co-authored-by: Antoine Augusti <antoine.augusti@transport.data.gouv.fr> * Update apps/transport/lib/transport_web/api/spec.ex Co-authored-by: Antoine Augusti <antoine.augusti@transport.data.gouv.fr> * Add note * Update apps/transport/test/transport_web/controllers/api/stats_controller_test.exs Co-authored-by: Antoine Augusti <antoine.augusti@transport.data.gouv.fr> * Fix broken test --------- Co-authored-by: Antoine Augusti <antoine.augusti@transport.data.gouv.fr>
etalab · Sep 4, 2023 · d8c1c89 · d8c1c89
1 parent 11d3a90
commit d8c1c89
Show file tree

Hide file tree

Showing 20 changed files with 763 additions and 130 deletions.
diff --git a/apps/transport/lib/transport_web/api/controllers/aom_controller.ex b/apps/transport/lib/transport_web/api/controllers/aom_controller.ex
@@ -16,8 +16,7 @@ defmodule TransportWeb.API.AomController do
   def by_coordinates_operation,
     do: %Operation{
       tags: ["aom"],
-      summary: "Show AOM by coordinates",
-      description: "Show covered regions",
+      summary: "Show first AOM containing a point with given coordinates",
       operationId: "API.AOMController.by_coordinates",
       parameters: [
         Operation.parameter(:lon, :query, :number, "Longitude"),
@@ -43,9 +42,8 @@ defmodule TransportWeb.API.AomController do
   @spec by_insee_operation :: OpenApiSpex.Operation.t()
   def by_insee_operation,
     do: %Operation{
-      tags: ["insee"],
-      summary: "Show AOM by INSEE",
-      description: "Show covered regions",
+      tags: ["aom"],
+      summary: "Search AOM by INSEE code",
       operationId: "API.AOMController.by_insee_operation",
       parameters: [
         Operation.parameter(:insee, :path, :string, "INSEE")
@@ -92,9 +90,8 @@ defmodule TransportWeb.API.AomController do
   @spec geojson_operation :: OpenApiSpex.Operation.t()
   def geojson_operation,
     do: %Operation{
-      tags: ["geojson"],
-      summary: "Show geojson of AOM",
-      description: "Show covered regions",
+      tags: ["aom"],
+      summary: "Show GeoJSON of all available AOMs (Autorités Organisatrices de la Mobilité)",
       operationId: "API.AOMController.geojson_operation",
       parameters: [],
       responses: %{

diff --git a/apps/transport/lib/transport_web/api/controllers/datasets_controller.ex b/apps/transport/lib/transport_web/api/controllers/datasets_controller.ex
@@ -4,7 +4,7 @@ defmodule TransportWeb.API.DatasetController do
   alias Helpers
   alias OpenApiSpex.Operation
   alias DB.{AOM, Dataset, Repo, Resource}
-  alias TransportWeb.API.Schemas.{DatasetsResponse, GeoJSONResponse}
+  alias TransportWeb.API.Schemas.{DatasetDetails, DatasetsResponse, GeoJSONResponse}
   alias Geo.{JSON, MultiPolygon}
 
   # The default (one minute) felt a bit too high for someone doing scripted operations
@@ -19,12 +19,15 @@ defmodule TransportWeb.API.DatasetController do
   def datasets_operation,
     do: %Operation{
       tags: ["datasets"],
-      summary: "Show datasets and its resources",
-      description: "For every dataset, show its associated resources, url and validity date",
+      summary: "List all datasets (with their resources)",
+      description: ~s"This call returns (in a single, non-paginated response) the list of all the
+                      datasets referenced on the site, along with their associated resources. The datasets
+                      and resources are here provided in summarized form (without history & conversions).
+                      You can call `/api/datasets/:id` for each dataset to get extra data (history & conversions)",
       operationId: "API.DatasetController.datasets",
       parameters: [],
       responses: %{
-        200 => Operation.response("Dataset", "application/json", DatasetsResponse)
+        200 => Operation.response("DatasetsResponse", "application/json", DatasetsResponse)
       }
     }
 
@@ -50,21 +53,22 @@ defmodule TransportWeb.API.DatasetController do
   def by_id_operation,
     do: %Operation{
       tags: ["datasets"],
-      summary: "Show given dataset and its resources",
-      description: "For one dataset, show its associated resources, url and validity date",
+      summary: "Return the details of a given dataset and its resources",
+      description:
+        ~s"Returns the detailed version of a dataset, showing its resources, the resources history & conversions.",
       operationId: "API.DatasetController.datasets_by_id",
-      parameters: [Operation.parameter(:id, :path, :string, "id")],
+      parameters: [Operation.parameter(:id, :path, :string, "datagouv id of the dataset you want to retrieve")],
       responses: %{
-        200 => Operation.response("Dataset", "application/json", DatasetsResponse)
+        200 => Operation.response("DatasetDetails", "application/json", DatasetDetails)
       }
     }
 
   @spec geojson_by_id_operation() :: Operation.t()
   def geojson_by_id_operation,
     do: %Operation{
       tags: ["datasets"],
-      summary: "Show given dataset geojson",
-      description: "For one dataset, show its associated geojson",
+      summary: "Show given dataset GeoJSON",
+      description: "For one dataset, show its associated GeoJSON.",
       operationId: "API.DatasetController.datasets_geojson_by_id",
       parameters: [Operation.parameter(:id, :path, :string, "id")],
       responses: %{
@@ -195,6 +199,7 @@ defmodule TransportWeb.API.DatasetController do
     )
   end
 
+  # NOTE: only added in detailed dataset view
   defp add_conversions(%{"resources" => resources} = data, %Dataset{} = dataset) do
     conversions =
       dataset

diff --git a/apps/transport/lib/transport_web/api/controllers/places_controller.ex b/apps/transport/lib/transport_web/api/controllers/places_controller.ex
@@ -79,7 +79,7 @@ defmodule TransportWeb.API.PlacesController do
     %Operation{
       tags: ["datasets"],
       summary: "Autocomplete search for datasets",
-      description: "Given a search input, return potentialy corresponding results with the associated url",
+      description: "Given a search input, return potentially corresponding results with the associated search URL",
       operationId: "API.DatasetController.datasets_autocomplete",
       parameters: [Operation.parameter(:q, :query, :string, "query")],
       responses: %{

diff --git a/apps/transport/lib/transport_web/api/controllers/stats_controller.ex b/apps/transport/lib/transport_web/api/controllers/stats_controller.ex
@@ -13,7 +13,7 @@ defmodule TransportWeb.API.StatsController do
   @spec regions_operation() :: Operation.t()
   def regions_operation,
     do: %Operation{
-      tags: ["regions"],
+      tags: ["stats"],
       summary: "Show regions",
       description: "Show covered french administrative regions",
       operationId: "API.StatsController.regions",
@@ -26,7 +26,7 @@ defmodule TransportWeb.API.StatsController do
   @spec index_operation() :: Operation.t()
   def index_operation,
     do: %Operation{
-      tags: ["index"],
+      tags: ["stats"],
       summary: "Show regions",
       description: "Show covered french administrative regions",
       operationId: "API.StatsController.index",
@@ -39,7 +39,7 @@ defmodule TransportWeb.API.StatsController do
   @spec bike_scooter_sharing_operation() :: Operation.t()
   def bike_scooter_sharing_operation,
     do: %Operation{
-      tags: ["bike-scooter-sharing"],
+      tags: ["stats"],
       summary: "Show bike and scooter sharing stats",
       description: "Show bike and scooter sharing stats",
       operationId: "API.StatsController.bike_scooter_sharing",
@@ -52,7 +52,7 @@ defmodule TransportWeb.API.StatsController do
   @spec quality_operation() :: Operation.t()
   def quality_operation,
     do: %Operation{
-      tags: ["quality"],
+      tags: ["stats"],
       summary: "Show data quality stats",
       description: "Show data quality stats",
       operationId: "API.StatsController.quality",
@@ -66,6 +66,7 @@ defmodule TransportWeb.API.StatsController do
   def geojson(features),
     do: %{
       "type" => "FeatureCollection",
+      # This is now completely incorrect!
       "name" => "Autorités organisatrices de Mobiltés",
       "features" => features
     }
@@ -376,6 +377,9 @@ defmodule TransportWeb.API.StatsController do
       %{
         "geometry" => r.geometry |> JSON.encode!(),
         "type" => "Feature",
+        # NOTE: there is a bug here - the key is an atom.
+        # I won't change it now because it would mean more changes somewhere else, maybe.
+        # `Map.reject(fn({k,v}) -> k == :geometry end)` will do it.
         "properties" => Map.take(r, Enum.filter(Map.keys(r), fn k -> k != "geometry" end))
       }
     end)

diff --git a/apps/transport/lib/transport_web/api/router.ex b/apps/transport/lib/transport_web/api/router.ex
@@ -60,7 +60,7 @@ defmodule TransportWeb.API.Router do
     do: %{
       info: %{
         version: "1.0",
-        title: "Transport.data.gouv.fr API"
+        title: "transport.data.gouv.fr API"
       }
     }
 end