Merge pull request #579 from jennydaman/openapi

Add drf-spectacular for OpenAPI generation

.github/workflows/ci.yml

@@ -30,10 +30,13 @@ jobs:
 
   build:
     needs: [ test ]
-    if: github.event_name == 'push' || github.event_name == 'release'
+    if: github.event_name == 'push'
     runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
+      - name: Update __version__.py
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: echo '__version__ = "${{ github.ref_name }}"' > chris_backend/__version__.py
       - name: Docker meta
         id: meta
         uses: docker/metadata-action@v5

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015 - 2023 FNNDSC / CHB
+Copyright (c) 2015 - 2024 FNNDSC / CHB
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

chris_backend/__version__.py

@@ -0,0 +1,5 @@
+"""
+Do not manually update the version number here. This file gets overwritten by CI.
+"""
+
+__version__ = '0.0.0+unknown'

chris_backend/config/settings/common.py

@@ -13,6 +13,14 @@
 
 from pathlib import Path
 
+from environs import Env
+
+from __version__ import __version__
+
+# Environment variables-based secrets
+env = Env()
+env.read_env()  # also read .env file, if it exists
+
 
 # Build paths inside the project like this: BASE_DIR / 'subdir'.
 BASE_DIR = Path(__file__).resolve().parent.parent.parent
@@ -32,6 +40,7 @@
     'rest_framework.authtoken',
     'corsheaders',
     'collectionjson',
+    'drf_spectacular',
     'core',
     'feeds',
     'plugins',
@@ -66,7 +75,8 @@
     ),
     'DEFAULT_FILTER_BACKENDS': (
         'django_filters.rest_framework.DjangoFilterBackend',
-    )
+    ),
+    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema'
 }
 
 MIDDLEWARE = [
@@ -163,3 +173,32 @@
 # https://docs.djangoproject.com/en/4.2/ref/settings/#default-auto-field
 
 DEFAULT_AUTO_FIELD = 'django.db.models.BigAutoField'
+
+# drf-spectacular OPENAPI SCHEMA SETTINGS
+SPECTACULAR_SETTINGS = {
+    'TITLE': 'ChRIS Research Integration System: Ultron BackEnd (CUBE) API',
+    'DESCRIPTION': (
+        'The ChRIS Ultron BackEnd (CUBE) is the core backend API of ChRIS. '
+        'It manages ChRIS users, plugins, pipelines, and the provenance of '
+        'data analyses as ChRIS feeds.'
+    ),
+    'VERSION': __version__,
+    'LICENSE': {
+        'name': 'MIT',
+        'url': 'https://github.com/FNNDSC/ChRIS_ultron_backEnd/blob/master/LICENSE'
+    },
+    'EXTERNAL_DOCS': {
+        'url': 'https://chrisproject.org/docs'
+    },
+    'CONTACT': {
+        'name': 'Fetal-Neonatal Neuroimaging Developmental Science Center',
+        'url': 'https://chrisproject.org',
+        'email': '[email protected]'
+    },
+    'SERVE_INCLUDE_SCHEMA': True,
+    'COMPONENT_SPLIT_REQUEST': env.bool("SPECTACULAR_SPLIT_REQUEST", False),
+
+    'SCHEMA_PATH_PREFIX': '/api/v1/',
+    # more settings found at:
+    # https://drf-spectacular.readthedocs.io/en/latest/settings.html
+}

chris_backend/config/urls.py

@@ -18,6 +18,7 @@
 from django.contrib import admin
 from django.urls import path, include
 from django.conf import settings
+from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView
 
 from plugins import admin as plugin_admin_views
 
@@ -41,6 +42,10 @@
     path('chris-admin/', admin.site.urls),
 
     path('api/', include('core.api')),
+
+    path('schema/', SpectacularAPIView.as_view(), name='schema'),
+    path('schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
+    path('schema/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
 ]
 
 if settings.DEBUG:

chris_backend/core/renderers.py

@@ -6,6 +6,7 @@ class BinaryFileRenderer(BaseRenderer):
     media_type = '*/*'
     charset = None
     render_style = 'binary'
+    format = 'binary'
 
     def render(self, data, media_type=None, renderer_context=None):
         return data    

docker-compose_just.yml

@@ -31,6 +31,7 @@ services:
     environment: &CHRIS_ENV
       DJANGO_SETTINGS_MODULE: "config.settings.local"
       STORAGE_ENV: "fslink"
+      SPECTACULAR_SPLIT_REQUEST: "true"
     user: ${UID:?Please run me using just.}:${GID:?Please run me using just.}
     profiles:
       - cube
@@ -192,6 +193,20 @@ services:
     command: chmod 777 /data
     restart: "no"
 
+  openapi-generator:
+    image: docker.io/openapitools/openapi-generator-cli:v7.8.0
+    volumes:
+      - ${OPENAPI_GENERATOR_OUTPUT:-./clients}:/out:rw
+    user: ${UID:?Please run me using just.}:${GID:?Please run me using just.}
+    profiles:
+      - cube
+      - tools
+    networks:
+      - local
+    depends_on:
+      chris:
+        condition: service_healthy
+
 volumes:
   chris_files:
   db:

justfile

@@ -152,3 +152,9 @@ prefer docker_or_podman:
 [group('(5) docker/podman preference')]
 unset-preference:
     rm -f .preference
+
+[group('(6) OpenAPI generator')]
+openapi-generate output +options:
+    mkdir -vp {{output}}
+    @env OPENAPI_GENERATOR_OUTPUT="$(realpath {{output}})" just docker-compose run --rm openapi-generator \
+        generate {{ options }} -i http://chris:8000/schema/ -o /out

requirements/base.txt

@@ -15,4 +15,5 @@ PyYAML==6.0.1
 whitenoise[brotli]==6.5.0
 PyJWT===2.8.0
 channels[daphne]==4.1.0
-nats-py==2.9.0
+nats-py==2.9.0
+drf-spectacular==0.27.2