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
|
||||
|
||||
# Documentation
|
||||
apidocs
|
||||
apidocs/python
|
||||
apidocs/http/*.json
|
||||
|
||||
# PyBuilder
|
||||
target/
|
||||
|
|
|
|||
|
|
@ -180,11 +180,13 @@ build-docs:
|
|||
- |
|
||||
pydoctor -W \
|
||||
--docformat restructuredtext \
|
||||
--html-output apidocs/python \
|
||||
--project-name "OpenFlexure Microscope Server" \
|
||||
--project-version $CI_COMMIT_REF_NAME \
|
||||
--theme readthedocs \
|
||||
--html-viewsource-base https://gitlab.com/openflexure/openflexure-microscope-server/-/tree/$CI_COMMIT_SHA/ \
|
||||
src/openflexure_microscope_server
|
||||
- ./generate_http_api_data.py
|
||||
- echo "JOB_ID=$CI_JOB_ID" > build-docs.env
|
||||
artifacts:
|
||||
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