Merge pull request open5e#740 from open5e/586-reliable-openapi-spec-generated

586 reliable openapi spec generated

Author: augustjohnson

.github/workflows/rdme-openapi.yml

@@ -19,19 +19,11 @@ jobs:
         with:
           python-version: "3.11"
 
-      - name: install pipenv
-        run: |
-          pip install pipenv
+      - name: build schema
+        run: sh ./scripts/generate_openapi_spec.sh
 
-      - name: install dependencies
-        run: |
-          pipenv install
 
-      - name: build oas file
-        run: |
-          pipenv run python manage.py spectacular --file openapi-schema.yml
-
-      - name: Run `openapi` command for v1🚀
+      - name: Run `openapi` command 🚀
         uses: readmeio/rdme@v8
         with:
           rdme: openapi openapi-schema.yml --key=${{ secrets.README_API_KEY }} --id=6715b7fb7960ee004eb4a8cf

Pipfile

@@ -12,7 +12,7 @@ newrelic = "*"
 requests = "*"
 whitenoise = "*"
 gunicorn = "*"
-drf-spectacular = "*"
+drf-spectacular = {extras = ["sidecar"], version = "*"}
 
 [dev-packages]
 pytest = "*"

Pipfile.lock

@@ -3,8 +3,9 @@
 from django.urls import path
 
 from api import views
+from server.routers import DocumentedDefaultRouter
 
-router = routers.DefaultRouter()
+router = DocumentedDefaultRouter()
 router.register(r'manifest', views.ManifestViewSet)
 router.register(r'spells', views.SpellViewSet)
 router.register(r'spelllist',views.SpellListViewSet)

api/urls.py

@@ -52,7 +52,7 @@ class ClassFeature(HasName, HasDescription, FromDocument):
 
     # Infer the type of this feature based on the `key`
     @property
-    def feature_type(self):
+    def feature_type(self) -> str:
         if "proficiency-bonus" in self.key: return "PROFICIENCY_BONUS"
         if "proficiencies" in self.key:     return "PROFICIENCIES"
         if "equipment" in self.key:         return "STARTING_EQUIPMENT"

api_v2/models/characterclass.py

@@ -35,7 +35,7 @@ def __str__(self):
         return (self.document.name + " - " + self.name)
 
     @property
-    def file_url(self):
+    def file_url(self)->str:
         return static(self.file_path)
 
     class Meta:

api_v2/models/image.py

@@ -70,7 +70,7 @@ class Meta:
         ]
 
     # Gathers 'uses_type' and 'uses_param' into a single 'usage_limits' obj.
-    def get_usage_limits(self, obj):
+    def get_usage_limits(self, obj)->dict:
         if obj.uses_type and obj.uses_param: 
             return {
                 'type': obj.uses_type,

api_v2/serializers/creature.py

@@ -0,0 +1,6 @@
+# This script takes the code repo as the input and generates an openapi spec as the output.
+# Parameters:
+# Version takes in a string that will be shown in the API docs.
+pip install pipenv
+pipenv install
+pipenv run python manage.py spectacular --color --file openapi-schema.yml --validate --fail-on-warn 

scripts/generate_openapi_spec.sh

@@ -0,0 +1,12 @@
+from rest_framework import routers
+
+class Open5eAPI(routers.APIRootView):
+    """
+    Welcome to the Open5e API.
+    You can review the basic DRF Browseable API here.
+    You can review swagger-ui at /schema/swagger-ui/
+    You can review redoc at /schema/redoc/
+    """
+
+class DocumentedDefaultRouter(routers.DefaultRouter):
+    APIRootView = Open5eAPI

server/routers.py

@@ -68,6 +68,7 @@
     'api_v2',
     'search',
 	'drf_spectacular',
+    'drf_spectacular_sidecar',
 
     # downloaded modules
     "rest_framework",
@@ -216,13 +217,20 @@
 )  # This setting allows the header from NGINX to tell us that the request is secured.
 
 SPECTACULAR_SETTINGS = {
+    'VERSION' : 'development',
     'TITLE': 'Open5e',
-    'DESCRIPTION': 'The Open5e API includes all monsters and spells from the SRD and other',
-    'SERVERS': [{'url': 'https://api.open5e.com', 'description': 'Production server'}],
+    'DESCRIPTION': 'The Open5e API. See [https://github.com/open5e/open5e-api] for more information.',
+    'SERVERS': [
+        {'url': 'https://api.open5e.com', 'description': 'Production server'},
+        {'url': 'https://api-beta.open5e.com', 'description': 'Beta server'},
+        {'url': 'http://localhost:8000', 'description': 'Localhost'}],
 	'PREPROCESSING_HOOKS': [
         'server.oas.custom_preprocessing_hook'
     ],
     'POSTPROCESSING_HOOKS': [
         'server.oas.custom_postprocessing_hook'
     ],
+    'SWAGGER_UI_DIST': 'SIDECAR',
+    'SWAGGER_UI_FAVICON_HREF': 'SIDECAR',
+    'REDOC_DIST': 'SIDECAR',
 }