Merge branch 'http-api-docs' into 'v3'
HTTP API docs Closes #531 See merge request openflexure/openflexure-microscope-server!473
This commit is contained in:
Joe Knapper
commit
8a2e2ca758
8 changed files with 203 additions and 71 deletions
3
.gitignore
vendored
3
.gitignore
vendored
|
|
@ -65,7 +65,8 @@ picamera_test_hashes.json
|
||||||
*.log
|
*.log
|
||||||
|
|
||||||
# Documentation
|
# Documentation
|
||||||
apidocs
|
apidocs/python
|
||||||
|
apidocs/http/*.json
|
||||||
|
|
||||||
# PyBuilder
|
# PyBuilder
|
||||||
target/
|
target/
|
||||||
|
|
|
||||||
|
|
@ -180,11 +180,13 @@ build-docs:
|
||||||
- |
|
- |
|
||||||
pydoctor -W \
|
pydoctor -W \
|
||||||
--docformat restructuredtext \
|
--docformat restructuredtext \
|
||||||
|
--html-output apidocs/python \
|
||||||
--project-name "OpenFlexure Microscope Server" \
|
--project-name "OpenFlexure Microscope Server" \
|
||||||
--project-version $CI_COMMIT_REF_NAME \
|
--project-version $CI_COMMIT_REF_NAME \
|
||||||
--theme readthedocs \
|
--theme readthedocs \
|
||||||
--html-viewsource-base https://gitlab.com/openflexure/openflexure-microscope-server/-/tree/$CI_COMMIT_SHA/ \
|
--html-viewsource-base https://gitlab.com/openflexure/openflexure-microscope-server/-/tree/$CI_COMMIT_SHA/ \
|
||||||
src/openflexure_microscope_server
|
src/openflexure_microscope_server
|
||||||
|
- ./generate_http_api_data.py
|
||||||
- echo "JOB_ID=$CI_JOB_ID" > build-docs.env
|
- echo "JOB_ID=$CI_JOB_ID" > build-docs.env
|
||||||
artifacts:
|
artifacts:
|
||||||
expire_in: 1 week
|
expire_in: 1 week
|
||||||
|
|
|
||||||
87
apidocs/http/index.html
Normal file
87
apidocs/http/index.html
Normal file
|
|
@ -0,0 +1,87 @@
|
||||||
|
<!DOCTYPE html>
|
||||||
|
<html>
|
||||||
|
<head>
|
||||||
|
<title>OpenFlexure Microscope HTTP API Docs</title>
|
||||||
|
|
||||||
|
<link href="https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;600&display=swap" rel="stylesheet">
|
||||||
|
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" />
|
||||||
|
|
||||||
|
<style>
|
||||||
|
|
||||||
|
.intro {
|
||||||
|
font-family: 'Open Sans', sans-serif;
|
||||||
|
max-width: 900px;
|
||||||
|
margin: 2.5rem auto 2rem;
|
||||||
|
padding: 0 1.5rem;
|
||||||
|
color: #2a2a2a;
|
||||||
|
}
|
||||||
|
|
||||||
|
.intro h1 {
|
||||||
|
color: #c5247f;
|
||||||
|
margin-bottom: 0.75rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
.intro p {
|
||||||
|
margin-bottom: 1rem;
|
||||||
|
line-height: 1.5;
|
||||||
|
}
|
||||||
|
|
||||||
|
.intro code {
|
||||||
|
background: #f5f5f5;
|
||||||
|
padding: 0.2rem 0.4rem;
|
||||||
|
border-radius: 4px;
|
||||||
|
font-size: 0.95rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
.intro aside {
|
||||||
|
margin-top: 1rem;
|
||||||
|
padding: 0.75rem 1rem;
|
||||||
|
background: #f8f8f8;
|
||||||
|
border-left: 4px solid #c5247f;
|
||||||
|
font-size: 0.9rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
#swagger-ui {
|
||||||
|
max-width: 1100px;
|
||||||
|
margin: 0 auto 3rem;
|
||||||
|
padding: 0 1rem;
|
||||||
|
}
|
||||||
|
</style>
|
||||||
|
</head>
|
||||||
|
|
||||||
|
<body>
|
||||||
|
|
||||||
|
<div class="intro">
|
||||||
|
<h1>OpenFlexure Microscope HTTP API</h1>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
These docs are provided for reference only. They cannot control a running microscope.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
For interactive documentation on a live microscope, visit:
|
||||||
|
<br>
|
||||||
|
<code>http://microscope.local:5000/docs</code>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<aside>
|
||||||
|
Replace <strong>microscope.local</strong> with your microscope's hostname or IP address
|
||||||
|
if your network uses a different name.
|
||||||
|
</aside>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div id="swagger-ui"></div>
|
||||||
|
|
||||||
|
<script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
|
||||||
|
<script>
|
||||||
|
window.onload = () => {
|
||||||
|
SwaggerUIBundle({
|
||||||
|
url: "./openapi.json",
|
||||||
|
dom_id: "#swagger-ui",
|
||||||
|
supportedSubmitMethods: [],
|
||||||
|
});
|
||||||
|
};
|
||||||
|
</script>
|
||||||
|
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
60
apidocs/index.html
Normal file
60
apidocs/index.html
Normal file
|
|
@ -0,0 +1,60 @@
|
||||||
|
<!DOCTYPE html>
|
||||||
|
<html lang="en">
|
||||||
|
<head>
|
||||||
|
<meta charset="UTF-8">
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||||
|
<title>OpenFlexure Microscope Server API Docs</title>
|
||||||
|
|
||||||
|
<link href="https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;600&display=swap" rel="stylesheet">
|
||||||
|
|
||||||
|
<style>
|
||||||
|
body {
|
||||||
|
font-family: 'Open Sans', sans-serif;
|
||||||
|
background: #fff;
|
||||||
|
color: #2a2a2a;
|
||||||
|
margin: 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
.content {
|
||||||
|
max-width: 700px;
|
||||||
|
margin: 4rem auto;
|
||||||
|
padding: 0 1.5rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
h1 {
|
||||||
|
color: #c5247f;
|
||||||
|
margin-bottom: 0.5rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
a {
|
||||||
|
display: block;
|
||||||
|
margin: 1rem 0;
|
||||||
|
padding: 0.75rem 1rem;
|
||||||
|
text-decoration: none;
|
||||||
|
border: 2px solid #c5247f;
|
||||||
|
color: #c5247f;
|
||||||
|
font-weight: 600;
|
||||||
|
border-radius: 6px;
|
||||||
|
width: fit-content;
|
||||||
|
transition: 0.15s ease;
|
||||||
|
}
|
||||||
|
|
||||||
|
a:hover {
|
||||||
|
background: #c5247f;
|
||||||
|
color: #fff;
|
||||||
|
}
|
||||||
|
</style>
|
||||||
|
</head>
|
||||||
|
|
||||||
|
<body>
|
||||||
|
|
||||||
|
<div class="content">
|
||||||
|
<h1>OpenFlexure Microscope Server API Docs</h1>
|
||||||
|
<p>Select documentation:</p>
|
||||||
|
|
||||||
|
<a href="./http/index.html">HTTP API (Swagger)</a>
|
||||||
|
<a href="./python/index.html">Python API</a>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
|
@ -1,24 +0,0 @@
|
||||||
# Minimal makefile for Sphinx documentation
|
|
||||||
#
|
|
||||||
|
|
||||||
# You can set these variables from the command line.
|
|
||||||
SPHINXOPTS = -a -E
|
|
||||||
SPHINXBUILD = sphinx-build
|
|
||||||
SOURCEDIR = source
|
|
||||||
BUILDDIR = build
|
|
||||||
|
|
||||||
# Put it first so that "make" without argument is like "make help".
|
|
||||||
help:
|
|
||||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
|
||||||
|
|
||||||
.PHONY: help Makefile
|
|
||||||
|
|
||||||
openapi: $(BUILDDIR)/swagger.yaml
|
|
||||||
|
|
||||||
$(BUILDDIR)/swagger.yaml: Makefile
|
|
||||||
ofm-generate-openapi -o $@
|
|
||||||
|
|
||||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
|
||||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
|
||||||
html dirhtml singlehtml json htmlhelp epub latex latexpdf text changes xml linkcheck doctest coverage clean: Makefile
|
|
||||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
|
||||||
|
|
@ -1,37 +0,0 @@
|
||||||
@ECHO OFF
|
|
||||||
|
|
||||||
pushd %~dp0
|
|
||||||
|
|
||||||
REM Command file for Sphinx documentation
|
|
||||||
|
|
||||||
if "%SPHINXBUILD%" == "" (
|
|
||||||
set SPHINXBUILD=sphinx-build
|
|
||||||
)
|
|
||||||
set SOURCEDIR=source
|
|
||||||
set BUILDDIR=build
|
|
||||||
|
|
||||||
set SPHINXOPTS="-E"
|
|
||||||
|
|
||||||
if "%1" == "" goto help
|
|
||||||
|
|
||||||
%SPHINXBUILD% >NUL 2>NUL
|
|
||||||
if errorlevel 9009 (
|
|
||||||
echo.
|
|
||||||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
|
|
||||||
echo.installed, then set the SPHINXBUILD environment variable to point
|
|
||||||
echo.to the full path of the 'sphinx-build' executable. Alternatively you
|
|
||||||
echo.may add the Sphinx directory to PATH.
|
|
||||||
echo.
|
|
||||||
echo.If you don't have Sphinx installed, grab it from
|
|
||||||
echo.http://sphinx-doc.org/
|
|
||||||
exit /b 1
|
|
||||||
)
|
|
||||||
|
|
||||||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
|
|
||||||
goto end
|
|
||||||
|
|
||||||
:help
|
|
||||||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
|
|
||||||
|
|
||||||
:end
|
|
||||||
popd
|
|
||||||
|
|
@ -1,9 +0,0 @@
|
||||||
sphinx_rtd_theme
|
|
||||||
numpy
|
|
||||||
labthings
|
|
||||||
expiringdict
|
|
||||||
sangaboard
|
|
||||||
typing_extensions
|
|
||||||
pillow
|
|
||||||
piexif
|
|
||||||
python-dateutil
|
|
||||||
52
generate_http_api_data.py
Executable file
52
generate_http_api_data.py
Executable file
|
|
@ -0,0 +1,52 @@
|
||||||
|
#! /usr/bin/env python3
|
||||||
|
"""Generate data about the HTTP API."""
|
||||||
|
|
||||||
|
import json
|
||||||
|
import os
|
||||||
|
from unittest import mock
|
||||||
|
|
||||||
|
from fastapi.testclient import TestClient
|
||||||
|
|
||||||
|
import labthings_fastapi as lt
|
||||||
|
|
||||||
|
ROOT_DIR = os.path.dirname(os.path.abspath(__file__))
|
||||||
|
|
||||||
|
|
||||||
|
def mock_picamera2_import() -> None:
|
||||||
|
"""Mock the picamera2 library so that the full config can be loaded."""
|
||||||
|
dummy_cam = mock.Mock()
|
||||||
|
mock_picamera2 = mock.MagicMock()
|
||||||
|
mock_picamera2.return_value.__enter__.return_value = dummy_cam
|
||||||
|
mock_picamera2.return_value.__exit__.return_value = None
|
||||||
|
mock.patch.dict(
|
||||||
|
"sys.modules",
|
||||||
|
{
|
||||||
|
"picamera2": mock_picamera2,
|
||||||
|
"picamera2.encoders": mock.Mock(),
|
||||||
|
"picamera2.outputs": mock.Mock(),
|
||||||
|
},
|
||||||
|
).start()
|
||||||
|
|
||||||
|
|
||||||
|
def main() -> None:
|
||||||
|
"""Generate openapi description and Thing descriptions."""
|
||||||
|
mock_picamera2_import()
|
||||||
|
config = os.path.join(ROOT_DIR, "ofm_config_full.json")
|
||||||
|
|
||||||
|
with open(config, "r", encoding="utf-8") as file_obj:
|
||||||
|
config_dict = json.load(file_obj)
|
||||||
|
|
||||||
|
config_dict["things"]["smart_scan"]["kwargs"]["scans_folder"] = "/tmp/scans"
|
||||||
|
|
||||||
|
server = lt.ThingServer(things=config_dict["things"])
|
||||||
|
test_client = TestClient(server.app)
|
||||||
|
td_response = test_client.get("/thing_descriptions/")
|
||||||
|
with open("apidocs/http/thing_descriptions.json", mode="w") as file_obj:
|
||||||
|
json.dump(td_response.json(), file_obj, indent=4)
|
||||||
|
openapi_response = test_client.get("/openapi.json")
|
||||||
|
with open("apidocs/http/openapi.json", mode="w") as f:
|
||||||
|
json.dump(openapi_response.json(), f, indent=4)
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
Loading…
Add table
Add a link
Reference in a new issue