Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Switch to Stoplight Elements for docs render #8

Merged
merged 5 commits into from
Dec 20, 2023
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Use Stoplight Elements for docs render
Switches to Stoplight Elements to render HTML version of API spec
samdbmg committed Dec 20, 2023
commit b93567e69f1d3e7da797fce8c53c50b4c0a16d42
2 changes: 1 addition & 1 deletion api/.gitignore
Original file line number Diff line number Diff line change
@@ -1 +1 @@
docs/TimeAddressableMediaStore.html
docs/TimeAddressableMediaStore_bundled.yaml
4 changes: 4 additions & 0 deletions api/.spectral.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
extends: spectral:oas
rules:
# Reduce severity of unused components: they're needed for docs readability
oas3-unused-component: info
14 changes: 7 additions & 7 deletions api/Dockerfile.multi
Original file line number Diff line number Diff line change
@@ -16,21 +16,21 @@ COPY ./schemas ./schemas
COPY ./TimeAddressableMediaStore.yaml .

###############################################################################
# Stage: oasvalidate - Validates OpenAPI specifications
# Stage: bundle - Bundles specification and schemas into a single file
###############################################################################
FROM redocly/openapi-cli AS oasvalidate
WORKDIR /data/
FROM redocly/cli as bundle

# Copy in documentation source files
COPY --from=layer /api /data

COPY .redocly.lint-ignore.yaml /data/

###############################################################################
# Stage: oasrender - Renders OpenAPI specifications
# Stage: oaslint - Validates OpenAPI specifications
###############################################################################
FROM ghcr.io/redocly/redoc/cli:v2.0.0-rc.59 AS oasrender
FROM stoplight/spectral:6.10 as oaslint

WORKDIR /data/

COPY .spectral.yaml /data/

# Copy in documentation source files
COPY --from=layer /api /data
21 changes: 12 additions & 9 deletions api/Makefile
Original file line number Diff line number Diff line change
@@ -3,20 +3,23 @@ topdir:=$(realpath $(dir $(word $(NUM_OF_PARENT),$(MAKEFILE_LIST))))

all: help


build-lint:
docker pull ap-docker.artifactory.labs.bbc/cloudfit/cloudfit_base:latest >/dev/null 2>/dev/null || true
DOCKER_BUILDKIT=1 docker build -f Dockerfile.multi --build-arg VERSION=0.0.1 --build-arg BUILD_TAG=local --target oasvalidate -t tams_api_oasvalidate:local .
docker pull stoplight/spectral:6.10 >/dev/null 2>/dev/null || true
DOCKER_BUILDKIT=1 docker build -f Dockerfile.multi --target oaslint -t tams_api_oaslint:local .

lint: build-lint
docker run --rm tams_api_oasvalidate:local lint /data/TimeAddressableMediaStore.yaml
docker run --rm tams_api_oaslint:local lint --fail-severity=warn /data/TimeAddressableMediaStore.yaml


build-bundle:
docker pull redocly/cli:latest >/dev/null 2>/dev/null || true
DOCKER_BUILDKIT=1 docker build -f Dockerfile.multi --target bundle -t tams_api_bundle:local .

build-render:
docker pull ap-docker.artifactory.labs.bbc/cloudfit/cloudfit_base:latest >/dev/null 2>/dev/null || true
DOCKER_BUILDKIT=1 docker build -f Dockerfile.multi --build-arg VERSION=0.0.1 --build-arg BUILD_TAG=local --target oasrender -t tams_api_oasrender:local .
docs/TimeAddressableMediaStore_bundled.yaml: build-bundle
docker run --rm tams_api_bundle:local bundle /data/TimeAddressableMediaStore.yaml > $@

render: build-render
docker run --rm -v "${topdir}/docs:/docs" tams_api_oasrender:local bundle /data/TimeAddressableMediaStore.yaml -o /docs/TimeAddressableMediaStore.html
render: docs/TimeAddressableMediaStore_bundled.yaml


mock-server-up:
@@ -40,4 +43,4 @@ help:
@echo "make mock-server-down - Stop the mock API server"
@echo "make mock-server-healthy - Connect to mock API server, confirm it is working"

.PHONY: all build-lint lint build-render render mock-server-up mock-server-down mock-server-healthy help
.PHONY: all build-lint lint build-bundle render mock-server-up mock-server-down mock-server-healthy help
13 changes: 9 additions & 4 deletions api/docs/index.html
Original file line number Diff line number Diff line change
@@ -1,9 +1,14 @@
<!DOCTYPE html>
<html>
<!doctype html>
<html lang="en">
<head>
<meta http-equiv="Refresh" content="0; url='TimeAddressableMediaStore.html'" />
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<title>Time Addressable Media API</title>

<script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css">
</head>
<body>
<p>Redirecting...</p>
<elements-api id="docs" router="hash" layout="sidebar" tryItEnabled="false" apiDescriptionUrl="./TimeAddressableMediaStore_bundled.yaml"></elements-api>
</body>
</html>