Render API docs (#6463)

* Render API docs

* Cleanup broken links

* Re-enable strict mode

* Change json to yaml

* Update docs/docs/api/schema.md

Co-authored-by: Matthias Mair <code@mjmair.com>

* Update docs/docs/api/schema.md

Co-authored-by: Matthias Mair <code@mjmair.com>

* Use neoteroi-mkdocs instead

- seems to render more reliably

* Fix SERVERS section for SPECTACTULAR_SETTINGS

* Script for splitting schema into smaller sections

* Generate an index file for the schema pages

* Move schema.md up one directory

* Fix formatting

* Remove tracked file

* Add hook for rebuilding API schema as part of RTD build

* Extract schema as RTD build step

* install invoke

* export env vars

* remove argparse

* Fix order of operations

* Compress env vars

* Remove custom env vars

- Now configured as part of RTD project

* Migrate db

* Revert "remove argparse"

This reverts commit 4665805340.

* Post-process generated schema file

* Fix file formatting

* Add note about schema repo

* no message

* Reduce schema overhead

* Ignore generated files

* Delete generated file

* Update .gitignore

* Add extra split for machine integration

* Remove schema files

- These will be auto-generated too

* Generate individual schema .md files

* Re-add .md files

- Need git commit log to work

* Update .gitignore

* Fix for CI test

* patch machine.api

* Revert previous change

* Formatting fix

* Adjust export step

* Bump API version

---------

Co-authored-by: Matthias Mair <code@mjmair.com>

InvenTree/InvenTree/api_version.py

@@ -1,11 +1,14 @@
 """InvenTree API version information."""
 
 # InvenTree API version
-INVENTREE_API_VERSION = 179
+INVENTREE_API_VERSION = 180
 """Increment this API version number whenever there is a significant change to the API that any clients need to know about."""
 
 INVENTREE_API_TEXT = """
 
+v180 - 2024-3-02 : https://github.com/inventree/InvenTree/pull/6463
+    - Tweaks to API documentation to allow automatic documentation generation
+
 v179 - 2024-03-01 : https://github.com/inventree/InvenTree/pull/6605
     - Adds "subcategories" count to PartCategory serializer
     - Adds "sublocations" count to StockLocation serializer

InvenTree/InvenTree/settings.py

@@ -469,21 +469,6 @@ if USE_JWT:
     INSTALLED_APPS.append('rest_framework_simplejwt')
 
 # WSGI default setting
-SPECTACULAR_SETTINGS = {
-    'TITLE': 'InvenTree API',
-    'DESCRIPTION': 'API for InvenTree - the intuitive open source inventory management system',
-    'LICENSE': {
-        'name': 'MIT',
-        'url': 'https://github.com/inventree/InvenTree/blob/master/LICENSE',
-    },
-    'EXTERNAL_DOCS': {
-        'description': 'More information about InvenTree in the official docs',
-        'url': 'https://docs.inventree.org',
-    },
-    'VERSION': str(inventreeApiVersion()),
-    'SERVE_INCLUDE_SCHEMA': False,
-}
-
 WSGI_APPLICATION = 'InvenTree.wsgi.application'
 
 """
@@ -1208,3 +1193,23 @@ if CUSTOM_FLAGS:
 # Magic login django-sesame
 SESAME_MAX_AGE = 300
 LOGIN_REDIRECT_URL = '/api/auth/login-redirect/'
+
+# Configuratino for API schema generation
+SPECTACULAR_SETTINGS = {
+    'TITLE': 'InvenTree API',
+    'DESCRIPTION': 'API for InvenTree - the intuitive open source inventory management system',
+    'LICENSE': {
+        'name': 'MIT',
+        'url': 'https://github.com/inventree/InvenTree/blob/master/LICENSE',
+    },
+    'EXTERNAL_DOCS': {
+        'description': 'More information about InvenTree in the official docs',
+        'url': 'https://docs.inventree.org',
+    },
+    'VERSION': str(inventreeApiVersion()),
+    'SERVE_INCLUDE_SCHEMA': False,
+    'SCHEMA_PATH_PREFIX': '/api/',
+}
+
+if SITE_URL:
+    SPECTACULAR_SETTINGS['SERVERS'] = [{'url': SITE_URL}]

InvenTree/machine/api.py

@@ -144,7 +144,9 @@ class MachineRestart(APIView):
 
     permission_classes = [permissions.IsAuthenticated]
 
-    @extend_schema(responses={200: MachineSerializers.MachineRestartSerializer()})
+    @extend_schema(
+        request=None, responses={200: MachineSerializers.MachineRestartSerializer()}
+    )
     def post(self, request, pk):
         """Restart machine by pk."""
         machine = get_machine(pk)