mirror of
https://github.com/mailscope/kumomta.git
synced 2026-09-06 10:38:56 +00:00
Wez Furlong
bd4e3f72c8
We currently use a rather hacky embedding of rapidoc to provide a generic browser around the jsonschema export from our API interface. It's not great for a couple of reasons: * The font sizes are tiny * The documentation rapidoc produces is not indexable, being generated by javascript when the browser loads. This also prevents making proper links to the various doc pages This commit introduces a little utility that we can use during the doc build to translate the schema into documentation files that can then be processed as normal by the build. This commit does this just for kumod at this time, but we could also add tsa daemon in the future if we expand its API surface.
39 lines
1.3 KiB
Bash
Executable File
39 lines
1.3 KiB
Bash
Executable File
#!/bin/sh
|
|
# This script updates the snapshot of the openapi specs for our
|
|
# various services, so that the mkdocs build can consume them
|
|
# to render the docs in the docs.
|
|
# It needs to be run manually after changing anything to do with the
|
|
# HTTP APIs.
|
|
|
|
# Only update the spec file if anything other than the version (which
|
|
# typically changes all the time during development, to track the current
|
|
# git hash) actually changed.
|
|
update_if_different() {
|
|
binary=$1
|
|
specfile=$2
|
|
|
|
candidate=$(mktemp)
|
|
trap "rm ${candidate}" "EXIT"
|
|
current=$(mktemp)
|
|
trap "rm ${current}" "EXIT"
|
|
|
|
$binary --dump-openapi-spec | blank_out_openapi_spec_version > $candidate
|
|
blank_out_openapi_spec_version < $specfile > $current
|
|
if ! cmp $candidate $current ; then
|
|
echo "$specfile updated"
|
|
$binary --dump-openapi-spec > $specfile
|
|
cargo run -p jsonschematodocs
|
|
fi
|
|
}
|
|
|
|
# Replace info.version with "blank" in an openapi json doc
|
|
blank_out_openapi_spec_version() {
|
|
jq --arg version 'blank' '.info.version = $version'
|
|
}
|
|
|
|
if hash jq 2>/dev/null ; then
|
|
CARGO_TARGET_DIR=${CARGO_TARGET_DIR:-${PWD}/target}
|
|
update_if_different ${CARGO_TARGET_DIR}/debug/kumod docs/reference/kumod.openapi.json
|
|
update_if_different ${CARGO_TARGET_DIR}/debug/tsa-daemon docs/reference/tsa-daemon.openapi.json
|
|
fi
|