fix redoc build and cleanup warnings (#185)

* fix redoc build and cleanup warnings
radiantearth · Aug 3, 2021 · 191a460 · 191a460
1 parent ab71e1c
commit 191a460
Show file tree

Hide file tree

Showing 9 changed files with 81 additions and 59 deletions.
diff --git a/.circleci/build-openapi.sh b/.circleci/build-openapi.sh
@@ -9,8 +9,7 @@ FNAMES=`find . -name "openapi.yaml" -not -path "./fragments/*" -not -path "./nod
 for fin in $FNAMES; do
     fout=./build/$fin
     mkdir -p ${fout%/*}
-    #speccy resolve $fin > $fout
-    swagger-cli bundle $fin -o $fout -t yaml
+    openapi bundle --ext yaml --output $fout $fin
     cp build/index.html ${fout%/*}/
 done
 

diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -24,7 +24,7 @@ jobs:
   validate:
     working_directory: ~/stac
     docker:
-      - image: circleci/node:12
+      - image: cimg/node:14
     steps:
       - checkout
       - save_cache:
@@ -44,7 +44,7 @@ jobs:
   build:
     working_directory: ~/stac
     docker:
-      - image: circleci/node:12
+      - image: cimg/node:14
     steps:
       - *restore_repo
       - *restore_dependencies
@@ -58,7 +58,7 @@ jobs:
   publish:
     working_directory: ~/stac
     docker:
-      - image: circleci/node:12
+      - image: cimg/node:14
     steps:
       - *restore_repo
       - *restore_dependencies
@@ -72,7 +72,7 @@ jobs:
   check-core-changes:
     working_directory: ~/stac
     docker:
-      - image: circleci/node:12
+      - image: cimg/node:14
     steps:
       - *restore_repo
       - *restore_dependencies

diff --git a/build/index.html b/build/index.html
@@ -1,20 +1,32 @@
-<html lang="en">
- <head>
-   <meta charset="utf-8">
-   <meta name="viewport" content="width=device-width,initial-scale=1">
-   <meta http-equiv="x-ua-compatible" content="ie=edge">
-   <link rel="shortcut icon" href="../assets/images/favicon.png">
-   <title>STAC API</title>
- </head>
- <body>
-   <div id="content"></div>
-   <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
-   <script type="text/javascript">
-     Redoc.init('openapi.yaml', {
-       expandResponses:"200,201,202,203,204",
-       pathInMiddlePanel: true,
-       hideDownloadButton: true
-     }, document.getElementById('content'));
-   </script>
- </body>
+<!DOCTYPE html>
+<html>
+
+<head>
+  <title>STAC API</title>
+  <!-- needed for adaptive design -->
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+
+  <!--
+    ReDoc doesn't change outer page styles
+    -->
+  <style>
+    body {
+      margin: 0;
+      padding: 0;
+    }
+  </style>
+</head>
+
+<body>
+  <redoc 
+    spec-url='openapi.yaml'
+    expandResponses='200,201,202,203,204'
+    pathInMiddlePanel='true'
+    hideDownloadButton='true'
+  ></redoc>
+  <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
+</body>
+
 </html>
diff --git a/build/swagger-config.yaml b/build/swagger-config.yaml
@@ -7,13 +7,7 @@ apis:
     paths:
       exclude:
         - "^\/$"
-  - url: 'build/ogcapi-features/openapi.yaml'
-  #- url: 'build/ogcapi-features/extensions/transaction/openapi.yaml'
-  #  dereference:
-  #    circular: ignore
   - url: 'build/item-search/openapi.yaml'
-    #dereference:
-    #  circular: ignore
+  - url: 'build/ogcapi-features/openapi.yaml'
   - url: 'build/ogcapi-features/extensions/version/openapi.yaml'
-    #dereference:
-    #  circular: ignore
+  - url: 'build/ogcapi-features/extensions/transaction/openapi.yaml'
diff --git a/core/README.md b/core/README.md
@@ -55,7 +55,7 @@ The following Link relations should exist in the Landing Page (root).
 | `root`         | `/`                  | STAC Core      | The root URI |
 | `self`         | `/`                  | OAFeat         | Self reference, same as root URI |
 | `service-desc` | `/api` (recommended) | OAFeat OpenAPI | The OpenAPI service description. Uses the `application/vnd.oai.openapi+json;version=3.0` media type to refer to the OpenAPI 3.0 document that defines the service's API |
-| `child`        | various              | STAC Core      | The child STAC Catalogs & Collections. Provides curated paths to get to STAC Collection and Item objects
+| `child`        | various              | STAC Core      | The child STAC Catalogs & Collections. Provides curated paths to get to STAC Collection and Item objects |
 
 Additionally, a `service-doc` endpoint is recommended.
 

diff --git a/fragments/filter/README.md b/fragments/filter/README.md
@@ -147,8 +147,10 @@ The implementation **must** support these conformance classes:
 
 It is **recommended** that the implementation also support the Basic Spatial Operators and Basic Temporal Operators classes:
 
-- Basic Spatial Operators (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:basic-spatial-operators`) defines the `INTERSECTS` predicate
-- Basic Temporal Operators: (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:basic-temporal-operators`) defines the `ANYINTERACTS` predicate
+- Basic Spatial Operators (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:basic-spatial-operators`)
+  defines the `INTERSECTS` predicate
+- Basic Temporal Operators: (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:basic-temporal-operators`)
+  defines the `ANYINTERACTS` predicate
 
 Additionally, the implementation **must** support at least one of the "CQL Text" or "CQL JSON" conformance classes that define 
 the CQL format used in the filter parameter:
@@ -163,19 +165,25 @@ CQL JSON in POST requests.
 The Filter Extension defines support for implementing the following conformance 
 classes. Implementation of these is often limited by the 
 operations supported by the implementation's datastore, for example, Elasticsearch does not support the spatial 
-operations required by the Enhanced Spatial Operators. If implemented for Item Search, the conformance class URI should follow
-the same pattern relative to OAFeat CQL.
-
-- Enhanced Comparison Operators (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:enhanced-comparison-operators`) defines the `LIKE`, `BETWEEN`, and `IN` operators. It is **recommended** to implement this class.
-- Enhanced Spatial Operators (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:enhanced-spatial-operators`) defines the same operators as OAF Part 3 CQL Enhanced Spatial Operators.
-- Enhanced Temporal Operators (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:enhanced-temporal-operators`) defines the same operators as OAF Part 3 CQL Enhanced Temporal Operators.
+operations required by the Enhanced Spatial Operators. If implemented for Item Search, the conformance class 
+URI should follow the same pattern relative to OAFeat CQL.
+
+- Enhanced Comparison Operators 
+  (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:enhanced-comparison-operators`) defines the `LIKE`, 
+  `BETWEEN`, and `IN` operators. It is **recommended** to implement this class.
+- Enhanced Spatial Operators 
+  (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:enhanced-spatial-operators`) defines the 
+  same operators as OAF Part 3 CQL Enhanced Spatial Operators.
+- Enhanced Temporal Operators 
+  (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:enhanced-temporal-operators`) defines the 
+  same operators as OAF Part 3 CQL Enhanced Temporal Operators.
 - Functions (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:functions`) defines the same operators as OAF Part 3 CQL Functions.
 - Arithmetic: (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:arithmetic`) defines the same operators as OAF Part 3 CQL Arithmetic.
 - Arrays: (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:arrays`) defines the same operators as OAF Part 3 CQL Arrays.
-- Queryable Operands: (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:queryable-operands`) allows the use 
-  of queryables (e.g., properties) in any position of a clause, not just in the first position. This allows predicates 
-  like `property1 == property2` be expressed, whereas the Basic CQL conformance class only requires comparisons against literal
-  values.
+- Queryable Operands: (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:queryable-operands`) allows the 
+  use of queryables (e.g., properties) in any position of a clause, not just in the first position. This allows 
+  predicates like `property1 == property2` be expressed, whereas the Basic CQL conformance class only requires
+  comparisons against literal values.
 
 Additionally, if an API implements the OGC API Features endpoint, it is **recommended** that the OAFeat Part 3 Filter, 
 Features Filter, and Basic CQL conformance classes be implemented, which allow use of CQL filters against the 

diff --git a/implementation.md b/implementation.md
@@ -30,8 +30,8 @@ permitting the `If-Match` request header.
 
 The datetime parameter used by the Item Search and Features conformance classes allows the same values as the 
 [OAF datetime](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_parameter_datetime) parameter. This allows for 
-either a single [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) datetime (e.g., `1990-12-31T23:59:59Z`) or a closed or single open ended interval that also 
-uses RFC 3339 datetimes (e.g., `1990-12-31T23:59:59Z/..`).
+either a single [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) datetime (e.g., `1990-12-31T23:59:59Z`) 
+or a closed or single open ended interval that also uses RFC 3339 datetimes (e.g., `1990-12-31T23:59:59Z/..`).
 
 RFC 3339 is a profile of ISO 8601, adding these constraints to the allowed values:
 - a complete representation of date and time (fractional seconds optional).
@@ -41,7 +41,7 @@ RFC 3339 is a profile of ISO 8601, adding these constraints to the allowed value
 
 A simple regex for an RFC 3339 datetime is:
 
-```
+```regex
 ^(\d\d\d\d)\-(\d\d)\-(\d\d)(T|t)(\d\d):(\d\d):(\d\d)([,.]\d+)?(Z|([-+])(\d\d):(\d\d))$
 ```
 
@@ -55,8 +55,13 @@ RFC 3339 datetime or an interval) is:
 
 1. uppercase the string (this avoids needing to match on both (t|T) and (z|Z))
 2. split the string on `/` to determine if it is a single datetime or an interval
-3. For the single value or each value of the split, check if it is either an open interval (the empty string or `..`), or if it matches the RFC3339 datetime regex. Only one of the interval ends may be open.
-5. ISO8601 parse datetime strings using a library such as [pyiso8601](https://github.com/micktwomey/pyiso8601) (Python), [dateutil](https://dateutil.readthedocs.io/en/stable/parser.html#dateutil.parser.isoparse) (Python), or [Luxon](https://github.com/moment/luxon/) (JavaScript). Frequently, date libraries built into language standard libraries do not parse ISO8601 datetimes correctly, for example, the built-in Python datetime library does not handle `Z` as a timezone.
+3. For the single value or each value of the split, check if it is either an open interval (the empty string or `..`), 
+   or if it matches the RFC3339 datetime regex. Only one of the interval ends may be open.
+4. ISO8601 parse datetime strings using a library such as [pyiso8601](https://github.com/micktwomey/pyiso8601) (Python), 
+   [dateutil](https://dateutil.readthedocs.io/en/stable/parser.html#dateutil.parser.isoparse) (Python), or 
+   [Luxon](https://github.com/moment/luxon/) (JavaScript). Frequently, date libraries built into language 
+   standard libraries do not parse ISO8601 datetimes correctly, for example, the built-in Python datetime 
+   library does not handle `Z` as a timezone.
 
 Below are a few examples of valid RFC 3339 datetimes. Note the uses of fractional seconds, the use of `.` or
  `,` as the fractional seconds separator, Z or z as a timezone, 
@@ -77,4 +82,4 @@ These are several examples of datetime intervals:
 - `../1990-12-31T23:59:59Z`
 - `1990-12-31T23:59:59Z/`
 - `1990-12-31T23:59:59Z/..`
-- `1990-12-31T23:59:59Z/1991-12-31T23:59:59Z`
+- `1990-12-31T23:59:59Z/1991-12-31T23:59:59Z`
diff --git a/item-search/README.md b/item-search/README.md
@@ -118,7 +118,11 @@ See [examples](examples.md) for some example requests.
 Only one of either **intersects** or **bbox** should be specified.  If both are specified, a 400 Bad Request response 
 should be returned. 
 
-**datetime** The datetime parameter use the same allowed values as the [OAF datetime](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_parameter_datetime) parameter. This allows for either a single [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) datetime or an open or closed interval that also uses RFC 3339 datetimes. Additional details about this parameter can be found in the [Implementation Recommendations](../implementation.md#datetime-parameter-handling).
+**datetime** The datetime parameter use the same allowed values as the 
+[OAF datetime](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_parameter_datetime) parameter. 
+This allows for either a single [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) datetime or an 
+open or closed interval that also uses RFC 3339 datetimes. Additional details about this parameter can be 
+found in the [Implementation Recommendations](../implementation.md#datetime-parameter-handling).
 
 **bbox** Represented using either 2D or 3D geometries. The length of the array must be 2\*n where 
 *n* is the number of dimensions. The array contains all axes of the southwesterly most extent 

diff --git a/package.json b/package.json
@@ -5,7 +5,7 @@
   "repository": "https://github.com/radiantearth/stac-api-spec",
   "license": "Apache-2.0",
   "scripts": {
-    "serve": "redoc-cli serve core/openapi.yaml --watch --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true",
+    "serve": "redoc-cli serve $npm_config_class/openapi.yaml --watch --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true",
     "check": "npm run check-markdown && npm run check-openapi",
     "check-markdown": "remark . -f -r .circleci/rc.yaml --ignore-pattern stac-spec/",
     "check-openapi": "npm run check-openapi-core && npm run check-openapi-commons && npm run check-openapi-ogcapi-features && npm run check-openapi-item-search && npm run check-openapi-fragments",
@@ -19,16 +19,16 @@
     "check-stac-spec-changes": "git diff --quiet HEAD ${npm_config_compare_to} -- stac-spec"
   },
   "dependencies": {
-    "@stoplight/spectral": "^5.7.1",
-    "gh-pages": "^3.1.0",
+    "@redocly/openapi-cli": "^1.0.0-beta.54",
+    "@stoplight/spectral": "^5.9.2",
+    "gh-pages": "^3.2.3",
+    "redoc-cli": "^0.12.2",
     "remark-cli": "^8.0.1",
     "remark-lint": "^7.0.1",
     "remark-lint-no-html": "^2.0.1",
     "remark-preset-lint-consistent": "^3.0.1",
     "remark-preset-lint-markdown-style-guide": "^3.0.1",
     "remark-preset-lint-recommended": "^4.0.1",
-    "remark-validate-links": "^10.0.2",
-    "swagger-cli": "^4.0.4",
-    "swagger-combine": "^1.3.0"
+    "remark-validate-links": "^10.0.2"
   }
 }