add catalog-info for backstage (#137)

* rebased

* added a catalog info and openapi schema

* renamed rest -> service as files have changed location

* removed outdated test_rest_api.py file

* modified catalog-info to include asyncapi, and made openapi.py output openapi.json into the same location as asyncapi.yaml

* removed catalog-info.yaml from pre commit checks to pass linting

* added CI job to automatically run openapi.py script to generate openapi schema

* changed name of CI job for openapi

* added test for openapi.py

* added openapi schema in docs

* using sphinxcontrib.openapi to autogenerate open api documentation

* added dependency to pyproject.toml

.github/workflows/openapi.yml

@@ -0,0 +1,30 @@
+name: Openapi
+
+on:
+  push:
+  pull_request:
+  schedule:
+    # Run weekly to check latest versions of dependencies
+    - cron: "0 8 * * WED"
+env:
+  # The target python version, which must match the Dockerfile version
+  CONTAINER_PYTHON: "3.11"
+
+jobs:
+  publish:
+    # pull requests are a duplicate of a branch push if within the same repo.
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Install python packages
+        uses: ./.github/actions/install_requirements
+        with:
+          requirements_file: requirements-dev-3.x.txt
+          install_options: -e .[dev]
+
+      - name: generate openapi schema
+        run: python src/blueapi/service/openapi.py

.pre-commit-config.yaml

@@ -4,7 +4,7 @@ repos:
     hooks:
       - id: check-added-large-files
       - id: check-yaml
-        exclude: ^helm\/.*\/templates\/.*
+        exclude: ^helm\/.*\/templates\/.*|catalog-info.yaml
       - id: check-merge-conflict
 
   - repo: local

catalog-info.yaml

@@ -0,0 +1,43 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: bluesky-worker
+  title: bluesky-worker
+  description: Lightweight wrapper around bluesky services
+  annotations:
+    github.com/project-slug: DiamondLightSouce/blueapi
+spec:
+  type: service
+  lifecycle: production
+  owner: user:vid18871 # TODO: owner: DAQ-Core
+  #  system: Athena  # TODO: Define Athena system: presumably same location as DAQ-Core/DAQ?
+  providesApis:
+    - message-topics
+    - restapi
+    - blueskydocument-to-scanmessage
+---
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: restapi
+  title: restapi
+  description: REST API for getting plans/devices from the worker (and running tasks)
+spec:
+  type: openapi
+  lifecycle: production
+  owner: user:vid18871
+  definition:
+    $text: ./docs/user/reference/openapi.json
+---
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: message-topics
+  title: message-topics
+  description: Message topics which can be listened to over an activeMQ message bus
+spec:
+  type: asyncapi
+  lifecycle: production
+  owner: user:vid18871
+  definition:
+    $text: ./docs/user/reference/asyncapi.yaml

docs/conf.py

@@ -42,6 +42,8 @@
     "sphinx_copybutton",
     # For the card element
     "sphinx_design",
+    # OpenAPI directive
+    "sphinxcontrib.openapi",
 ]
 
 # If true, Sphinx will warn about all references where the target cannot

docs/user/index.rst

@@ -52,6 +52,7 @@ side-bar.
 
             reference/api
             reference/asyncapi
+            reference/openapi
             ../genindex
 
         +++