Add OpenAPI spec files for EMS File and Tile services (#196)

* Add OpenAPI spec files for EMS File and Tile services

* Add note to changelog

* rename Makefile

Author: jsanz

CHANGELOG.md

@@ -6,6 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ## [8.5.1] TBD
 
 - Update release documentation #194
+- Include OpenAPI specification #196
 
 ## [8.5.0] - 2023-08-23
 

docs/openapi/Makefile

@@ -0,0 +1,35 @@
+.DEFAULT_GOAL=help
+
+.PHONY: help
+help:  ## Show this help message
+	@awk 'BEGIN {FS = ":.*##"; printf "Usage: make \033[36m<target>\033[0m\n\nTargets:\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
+
+.PHONY: clean
+clean: ## remove generated spec files
+	find . -name "bundled.*" -delete
+
+.PHONY: validate
+validate: ## Validate the specs
+	@npx swagger-cli validate "ems_file_service/entrypoint.yaml"
+	@npx swagger-cli validate "ems_tile_service/entrypoint.yaml"
+
+.PHONY: dev-validate
+dev-validate: ## Listen for changes on specs and validate
+	ls ems_file_service/entrypoint.yaml  ems_tile_service/entrypoint.yaml \
+  | entr -c make validate
+
+.PHONY: bundle
+bundle:
+	for e in ems_file_service ems_tile_service; do \
+    for f in yaml json; do \
+      npx @redocly/cli bundle \
+        --output "$${e}/bundled.$${f}" \
+        --ext "$${f}" "$${e}/entrypoint.yaml";\
+    done; \
+  done;
+	$(MAKE) lint
+
+.PHONY: lint
+lint: ## lint bundled.json
+	@npx @redocly/cli lint ems_file_service/bundled.json
+	@npx @redocly/cli lint ems_tile_service/bundled.json

docs/openapi/README.md

@@ -0,0 +1,41 @@
+# OpenAPI (Experimental)
+
+Spec files for Elastic Map Service manifests can be used for online tools like those found at https://openapi.tools/. 
+
+* **EMS Tile Service** as [JSON](https://raw.githubusercontent.com/elastic/ems-client/master/docs/openapi/ems_tile_service/bundled.json) or [YAML](https://raw.githubusercontent.com/elastic/ems-client/master/docs/openapi/ems_tile_service/bundled.yaml)
+* **EMS File Service** as [JSON](https://raw.githubusercontent.com/elastic/ems-client/master/docs/openapi/ems_file_service/bundled.json) or [YAML](https://raw.githubusercontent.com/elastic/ems-client/master/docs/openapi/ems_file_service/bundled.yaml)
+
+
+A guide about the openApi specification can be found at [https://swagger.io/docs/specification/about/](https://swagger.io/docs/specification/about/).
+
+## Tools
+
+You can use the `Makefile` script with the `validate`, `bundle`, and `clean` targets.
+
+Alternatively, you can run this validate the docs before bundling them with the following command in the `docs/openapi/` folder:
+
+  ```bash
+for e in ems_file_service ems_tile_service; do
+  npx swagger-cli validate "${e}/entrypoint.yaml"; 
+done
+  ```
+
+Then you can generate the `bundled` files by running the following commands:
+
+  ```bash
+for e in ems_file_service ems_tile_service; do
+  for f in yaml json; do
+    npx @redocly/cli bundle \
+      --output "${e}/bundled.${f}" \
+      --ext "${f}" "${e}/entrypoint.yaml"
+  done
+done
+  ```
+
+You can run additional linting with the following command:
+
+```bash
+for e in ems_file_service ems_tile_service; do
+  npx @redocly/cli lint "${e}/bundled.json"; 
+done
+```

docs/openapi/components/attribution.yaml

@@ -0,0 +1,19 @@
+type: array
+description: The attribution of this data
+minItems: 1
+items:
+  type: object
+  properties:
+    label:
+      type: object
+      properties:
+        en:
+          type: string
+          description: English attribution label
+    url:
+      type: object
+      properties:
+        en:
+          type: string
+          description: Attribution details URL
+          format: URL

docs/openapi/components/examples/file_service_200.json

@@ -0,0 +1 @@
+{ "version": "2023-10-31", "layers": [ { "layer_id": "world_countries", "created_at": "2020-10-28T16:16:08.720286", "attribution": [ { "label": { "en": "Made with NaturalEarth" }, "url": { "en": "http://www.naturalearthdata.com/about/terms-of-use" } }, { "label": { "en": "OpenStreetMap contributors" }, "url": { "en": "https://www.openstreetmap.org/copyright" } }, { "label": { "en": "Elastic Maps Service" }, "url": { "en": "https://www.elastic.co/elastic-maps-service" } } ], "formats": [ { "type": "topojson", "url": "/files/world_countries_v7.topo.json", "legacy_default": true, "meta": { "feature_collection_path": "data" } }, { "type": "geojson", "url": "/files/world_countries_v7.geo.json", "legacy_default": false } ], "fields": [ { "type": "id", "id": "iso2", "label": { "en": "ISO 3166-1 alpha-2 code", "af": "landkode (ISO 3166-1 alpha-2)", "ar": "أيزو 3166-1 حرفي-2" }, "regex": "^[A-Z]{2}$", "alias": ["(geo\\.){0,}country_iso_code$", "(country|countries)"], "values": ["AD", "AE", "ZW"] }, { "type": "id", "id": "iso3", "label": { "en": "ISO 3166-1 alpha-3 code", "af": "landkode (ISO 3166-1 alpha-3)", "ar": "أيزو 3166-1 حرفي-3" }, "regex": "^[A-Z]{3}$", "values": ["AND", "ARE", "ZWE"] }, { "type": "id", "id": "iso_numeric", "label": { "en": "ISO 3166-1 numeric code", "af": "landkode (ISO 3166-1 numeries)", "ar": "رمز إيزو الرقمي 3166-1" } }, { "type": "property", "id": "name", "label": { "en": "name", "am": "ስም" }, "alias": ["(country|countries)"] } ], "legacy_ids": ["World Countries"], "layer_name": { "en": "World Countries", "zh-tw": "國家" } }, { "layer_id": "administrative_regions_lvl2", "created_at": "2020-07-06T22:19:49.290894", "attribution": [ { "label": { "en": "Made with NaturalEarth" }, "url": { "en": "http://www.naturalearthdata.com/about/terms-of-use" } }, { "label": { "en": "OpenStreetMap contributors" }, "url": { "en": "https://www.openstreetmap.org/copyright" } }, { "label": { "en": "Elastic Maps Service" }, "url": { "en": "https://www.elastic.co/elastic-maps-service" } } ], "formats": [ { "type": "topojson", "url": "/files/admin_regions_lvl2_v2.topo.json", "legacy_default": true, "meta": { "feature_collection_path": "data" } }, { "type": "geojson", "url": "/files/admin_regions_lvl2_v2.geo.json", "legacy_default": false } ], "fields": [ { "type": "id", "id": "region_iso_code", "label": { "en": "Region ISO code" }, "regex": "^[A-Z]{2}-[A-Z0-9]{1,3}~?$", "alias": ["(geo\\.){0,}region_iso_code"], "values": ["AD-02", "AD-03", "AD-04"] }, { "type": "property", "id": "region_name", "label": { "en": "Region name" } }, { "type": "property", "id": "country_iso2_code", "label": { "en": "Country ISO2 code" } }, { "type": "property", "id": "country_iso3_code", "label": { "en": "Country ISO3 code" } }, { "type": "property", "id": "country_name", "label": { "en": "Country name" } } ], "legacy_ids": ["Administrative regions"], "layer_name": { "en": "Administrative regions", "zh-sg": "行政领土实体", "zh-tw": "行政領土實體" } }, { "layer_id": "albania_counties", "created_at": "2019-08-06T22:16:16.377Z", "attribution": [ { "label": { "en": "OpenStreetMap contributors" }, "url": { "en": "https://www.openstreetmap.org/copyright" } }, { "label": { "en": "Elastic Maps Service" }, "url": { "en": "https://www.elastic.co/elastic-maps-service" } } ], "formats": [ { "type": "geojson", "url": "/files/albania_counties_v1.geo.json", "legacy_default": true } ], "fields": [ { "type": "id", "id": "iso_3166_2", "label": { "en": "ISO 3166-2 code", "af": "ISO 3166-2", "ar": "أيزو 3166-2" }, "values": ["AL-05", "AL-01", "AL-12"] }, { "type": "property", "id": "label_en", "label": { "en": "name (en)", "am": "ስም (en)", "ar": "الاسم (en)" } }, { "type": "property", "id": "label_sq", "label": { "en": "name (sq)", "am": "ስም (sq)", "ar": "الاسم (sq)" } } ], "legacy_ids": ["Albania Counties"], "layer_name": { "en": "Albania Counties", "zh-sg": "阿尔巴尼亚行政区划", "zh-tw": "阿爾巴尼亞行政區劃" } } ] }

docs/openapi/components/examples/file_service_404.xml

@@ -0,0 +1 @@
+<?xml version='1.0' encoding='UTF-8'?><Error><Code>NoSuchKey</Code><Message>The specified key does not exist.</Message></Error>

docs/openapi/components/examples/tile_service_200.json

@@ -0,0 +1 @@
+{"version": "2023-10-31", "services": [{"id": "road_map", "name": {"en": "Classic"}, "attribution": [{"label": {"en": "OpenStreetMap contributors"}, "url": {"en": "https://www.openstreetmap.org/copyright"}}, {"label": {"en": "OpenMapTiles"}, "url": {"en": "https://openmaptiles.org"}}, {"label": {"en": "Elastic Maps Service"}, "url": {"en": "https://www.elastic.co/elastic-maps-service"}}], "formats": [{"locale": "en", "format": "vector", "url": "/2023-10-31/styles/osm-bright/style.json"}, {"locale": "en", "format": "raster", "url": "/2023-10-31/styles/osm-bright.json"}]}, {"id": "road_map_desaturated", "name": {"en": "Light"}, "attribution": [{"label": {"en": "OpenStreetMap contributors"}, "url": {"en": "https://www.openstreetmap.org/copyright"}}, {"label": {"en": "OpenMapTiles"}, "url": {"en": "https://openmaptiles.org"}}, {"label": {"en": "Elastic Maps Service"}, "url": {"en": "https://www.elastic.co/elastic-maps-service"}}], "formats": [{"locale": "en", "format": "vector", "url": "/2023-10-31/styles/osm-bright-desaturated/style.json"}, {"locale": "en", "format": "raster", "url": "/2023-10-31/styles/osm-bright-desaturated.json"}]}, {"id": "dark_map", "name": {"en": "Dark"}, "attribution": [{"label": {"en": "OpenStreetMap contributors"}, "url": {"en": "https://www.openstreetmap.org/copyright"}}, {"label": {"en": "OpenMapTiles"}, "url": {"en": "https://openmaptiles.org"}}, {"label": {"en": "Elastic Maps Service"}, "url": {"en": "https://www.elastic.co/elastic-maps-service"}}], "formats": [{"locale": "en", "format": "vector", "url": "/2023-10-31/styles/dark-matter/style.json"}, {"locale": "en", "format": "raster", "url": "/2023-10-31/styles/dark-matter.json"}]}]}

docs/openapi/components/examples/tile_service_404.html

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Error</title>
+</head>
+<body>
+<pre>Cannot GET /snthstn</pre>
+</body>
+</html>