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 4665805. * 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 · Mar 2, 2024 · 39ba25c · 39ba25c
1 parent d39ab9c
commit 39ba25c
Show file tree

Hide file tree

Showing 39 changed files with 1,867 additions and 33 deletions.
diff --git a/.github/workflows/qc_checks.yaml b/.github/workflows/qc_checks.yaml
@@ -144,7 +144,7 @@ jobs:
           dev-install: true
           update: true
       - name: Export API Documentation
-        run: invoke schema --ignore-warnings
+        run: invoke schema --ignore-warnings --filename InvenTree/schema.yml
       - name: Upload schema
         uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 # pin@v3.1.3
         with:
@@ -160,7 +160,7 @@ jobs:
           echo "URL: $url"
           curl -s -o api.yaml $url
           echo "Downloaded api.yaml"
-      - name: Check for differences in schemas
+      - name: Check for differences in API Schema
         if: needs.paths-filter.outputs.api == 'false'
         run: |
           diff --color -u InvenTree/schema.yml api.yaml

diff --git a/.gitignore b/.gitignore
@@ -104,3 +104,7 @@ api.yaml
 
 # web frontend (static files)
 InvenTree/web/static
+
+# Generated docs files
+docs/docs/api/*.yml
+docs/docs/api/schema/*.yml
diff --git a/InvenTree/InvenTree/api_version.py b/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

diff --git a/InvenTree/InvenTree/settings.py b/InvenTree/InvenTree/settings.py
@@ -469,21 +469,6 @@
     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 @@
 # 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}]
diff --git a/InvenTree/machine/api.py b/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)

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -10,6 +10,9 @@ env/
 _build/
 site/
 
+# Generated API schema files
+docs/api/schema/*.yml
+
 # Temp files
 releases.json
 versions.json

diff --git a/docs/docs/api/api.md b/docs/docs/api/api.md
@@ -17,6 +17,17 @@ The API is self-documenting, and the documentation is provided alongside any Inv
 {% include 'img.html' %}
 {% endwith %}
 
+### Schema Description
+    The API schema is also documented in the [API Schema](./schema.md) page.
+
+### Generating Schema File
+
+If you want to generate the API schema file yourself (for example to use with an external client, use the `invoke schema` command. Run with the `-help` command to see available options.
+
+```
+invoke schema -help
+```
+
 ## Authentication
 
 Users must be authenticated to gain access to the InvenTree API. The API accepts either basic username:password authentication, or token authentication. Token authentication is recommended as it provides much faster API access.

diff --git a/docs/docs/api/schema.md b/docs/docs/api/schema.md
@@ -0,0 +1,40 @@
+---
+title: InvenTree API Schema
+---
+
+The InvenTree API is implemented using the [Django REST framework](https://www.django-rest-framework.org).
+The API schema as documented below is generated using the [drf-spectactular](https://github.com/tfranzel/drf-spectacular/) extension.
+
+## API Version
+
+This documentation is for API version: `171`
+
+!!! tip "API Schema History"
+    We track API schema changes, and provide a snapshot of each API schema version in the [API schema repository](https://github.com/inventree/schema/).
+
+## API Schema File
+
+The API schema file is available for download, and can be used for generating client libraries, or for testing API endpoints.
+
+## API Schema Documentation
+
+API schema documentation is split into the following categories:
+
+| Category | Description |
+| --- | --- |
+| [Authorization and Authentication](./schema/auth.md) | Authorization and Authentication |
+| [Background Task Management](./schema/background-task.md) | Background Task Management |
+| [Barcode Scanning](./schema/barcode.md) | Barcode Scanning |
+| [Bill of Materials](./schema/bom.md) | Bill of Materials |
+| [Build Order Management](./schema/build.md) | Build Order Management |
+| [Company Management](./schema/company.md) | Company Management |
+| [Label Printing](./schema/label.md) | Label Printing |
+| [External Machine Management](./schema/machine.md) | External Machine Management |
+| [External Order Management](./schema/order.md) | External Order Management |
+| [Parts and Part Categories](./schema/part.md) | Parts and Part Categories |
+| [Plugin Functionality](./schema/plugins.md) | Plugin Functionality |
+| [Report Generation](./schema/report.md) | Report Generation |
+| [Settings Management](./schema/settings.md) | Settings Management |
+| [Stock and Stock Locations](./schema/stock.md) | Stock and Stock Locations |
+| [User Management](./schema/user.md) | User Management |
+| [General](./schema/general.md) | General API endpoints |
diff --git a/docs/docs/api/schema/auth.md b/docs/docs/api/schema/auth.md
@@ -0,0 +1,7 @@
+---
+title: Authorization and Authentication
+---
+
+The *Authorization and Authentication* section of the InvenTree API schema is documented below.
+
+[OAD(./docs/docs/api/schema/auth.yml)]
diff --git a/docs/docs/api/schema/background-task.md b/docs/docs/api/schema/background-task.md
@@ -0,0 +1,7 @@
+---
+title: Background Task Management
+---
+
+The *Background Task Management* section of the InvenTree API schema is documented below.
+
+[OAD(./docs/docs/api/schema/background-task.yml)]
diff --git a/docs/docs/api/schema/barcode.md b/docs/docs/api/schema/barcode.md
@@ -0,0 +1,7 @@
+---
+title: Barcode Scanning
+---
+
+The *Barcode Scanning* section of the InvenTree API schema is documented below.
+
+[OAD(./docs/docs/api/schema/barcode.yml)]
diff --git a/docs/docs/api/schema/bom.md b/docs/docs/api/schema/bom.md
@@ -0,0 +1,7 @@
+---
+title: Bill of Materials
+---
+
+The *Bill of Materials* section of the InvenTree API schema is documented below.
+
+[OAD(./docs/docs/api/schema/bom.yml)]
diff --git a/docs/docs/api/schema/build.md b/docs/docs/api/schema/build.md
@@ -0,0 +1,7 @@
+---
+title: Build Order Management
+---
+
+The *Build Order Management* section of the InvenTree API schema is documented below.
+
+[OAD(./docs/docs/api/schema/build.yml)]
diff --git a/docs/docs/api/schema/company.md b/docs/docs/api/schema/company.md
@@ -0,0 +1,7 @@
+---
+title: Company Management
+---
+
+The *Company Management* section of the InvenTree API schema is documented below.
+
+[OAD(./docs/docs/api/schema/company.yml)]
diff --git a/docs/docs/api/schema/general.md b/docs/docs/api/schema/general.md
@@ -0,0 +1,7 @@
+---
+title: General API Endpoints
+---
+
+The *General API Endpoints* section of the InvenTree API schema is documented below.
+
+[OAD(./docs/docs/api/schema/general.yml)]
diff --git a/docs/docs/api/schema/label.md b/docs/docs/api/schema/label.md
@@ -0,0 +1,7 @@
+---
+title: Label Printing
+---
+
+The *Label Printing* section of the InvenTree API schema is documented below.
+
+[OAD(./docs/docs/api/schema/label.yml)]
diff --git a/docs/docs/api/schema/machine.md b/docs/docs/api/schema/machine.md
@@ -0,0 +1,7 @@
+---
+title: External Machine Management
+---
+
+The *External Machine Management* section of the InvenTree API schema is documented below.
+
+[OAD(./docs/docs/api/schema/machine.yml)]
diff --git a/docs/docs/api/schema/order.md b/docs/docs/api/schema/order.md
@@ -0,0 +1,7 @@
+---
+title: External Order Management
+---
+
+The *External Order Management* section of the InvenTree API schema is documented below.
+
+[OAD(./docs/docs/api/schema/order.yml)]
diff --git a/docs/docs/api/schema/part.md b/docs/docs/api/schema/part.md
@@ -0,0 +1,7 @@
+---
+title: Parts and Part Categories
+---
+
+The *Parts and Part Categories* section of the InvenTree API schema is documented below.
+
+[OAD(./docs/docs/api/schema/part.yml)]
diff --git a/docs/docs/api/schema/plugins.md b/docs/docs/api/schema/plugins.md
@@ -0,0 +1,7 @@
+---
+title: Plugin Functionality
+---
+
+The *Plugin Functionality* section of the InvenTree API schema is documented below.
+
+[OAD(./docs/docs/api/schema/plugins.yml)]
diff --git a/docs/docs/api/schema/report.md b/docs/docs/api/schema/report.md
@@ -0,0 +1,7 @@
+---
+title: Report Generation
+---
+
+The *Report Generation* section of the InvenTree API schema is documented below.
+
+[OAD(./docs/docs/api/schema/report.yml)]
diff --git a/docs/docs/api/schema/settings.md b/docs/docs/api/schema/settings.md
@@ -0,0 +1,7 @@
+---
+title: Settings Management
+---
+
+The *Settings Management* section of the InvenTree API schema is documented below.
+
+[OAD(./docs/docs/api/schema/settings.yml)]
diff --git a/docs/docs/api/schema/stock.md b/docs/docs/api/schema/stock.md
@@ -0,0 +1,7 @@
+---
+title: Stock and Stock Locations
+---
+
+The *Stock and Stock Locations* section of the InvenTree API schema is documented below.
+
+[OAD(./docs/docs/api/schema/stock.yml)]
diff --git a/docs/docs/api/schema/user.md b/docs/docs/api/schema/user.md
@@ -0,0 +1,7 @@
+---
+title: User Management
+---
+
+The *User Management* section of the InvenTree API schema is documented below.
+
+[OAD(./docs/docs/api/schema/user.yml)]
diff --git a/docs/docs/concepts/units.md b/docs/docs/concepts/units.md
@@ -48,7 +48,7 @@ The [unit of measure](../part/part.md#units-of-measure) field for the [Part](../
 
 ### Supplier Part
 
-The [supplier part](../part/part/#supplier-parts) model uses real-world units to convert between supplier part quantities and internal stock quantities. Unit conversion rules ensure that only compatible unit types can be supplied
+The [supplier part](../part/part.md/#supplier-parts) model uses real-world units to convert between supplier part quantities and internal stock quantities. Unit conversion rules ensure that only compatible unit types can be supplied
 
 ### Part Parameter
 

diff --git a/docs/docs/extend/plugins/tags.md b/docs/docs/extend/plugins/tags.md
@@ -8,7 +8,7 @@ Several models in InvenTree can be tagged with arbitrary tags. Tags are useful f
 Tags are shared between all models that can be tagged.
 
 The following models can be tagged:
-- [Parts](../../part/part.md) and [Supplier Parts](../../order/company#supplier-parts)/[Manufacturer Part](../../order/company#manufacturer-parts)
+- [Parts](../../part/part.md) and [Supplier Parts](../../order/company.md#supplier-parts)/[Manufacturer Part](../../order/company.md#manufacturer-parts)
 - [Stock Items](../../stock/stock.md#stock-item) / [Stock Location](../../stock/stock.md#stock-location)
 
 

diff --git a/docs/docs/part/create.md b/docs/docs/part/create.md
@@ -64,6 +64,6 @@ If the *Add Supplier Data* option is checked, then supplier part and manufacture
 
 The following alternative methods for creating parts are supported:
 
-- [Via the REST API](../../api/api)
-- [Using the Python library](../../api/python)
-- [Within the Admin interface](../../settings/admin)
+- [Via the REST API](../api/api.md)
+- [Using the Python library](../api/python/python.md)
+- [Within the Admin interface](../settings/admin.md)
diff --git a/docs/docs/part/notification.md b/docs/docs/part/notification.md
@@ -7,7 +7,7 @@ title: Part Notifications
 Users can select to receive notifications when certain events occur.
 
 !!! warning "Email Configuration Required"
-    External notifications require correct [email configuration](../../start/config/#email-settings). They also need to be enabled in the settings under notifications`.
+    External notifications require correct [email configuration](../start/config.md#email-settings). They also need to be enabled in the settings under notifications`.
 
 !!! warning "Valid Email Address"
     Each user must have a valid email address associated with their account to receive email notifications
@@ -50,7 +50,7 @@ Any users who are subscribed to notifications for the part in question will rece
 
 ### Build Order Notification
 
-When a new [Build Order](../../build/build/) is created, the InvenTree software checks to see if any of the parts required to complete the order are low on stock.
+When a new [Build Order](../build/build.md) is created, the InvenTree software checks to see if any of the parts required to complete the order are low on stock.
 
 If there are any parts with low stock, a notification is generated for any users subscribed to notifications for the part being built.
 

diff --git a/docs/docs/part/trackable.md b/docs/docs/part/trackable.md
@@ -2,7 +2,7 @@
 title: Trackable Parts
 ---
 
-Denoting a part as *Trackble* changes the way that [stock items](../../stock/stock) associated with the particular part are handled in the database. A trackable part also has more restrictions imposed by the database scheme.
+Denoting a part as *Trackble* changes the way that [stock items](../stock/stock.md) associated with the particular part are handled in the database. A trackable part also has more restrictions imposed by the database scheme.
 
 ## Stock Tracking
 

diff --git a/docs/docs/releases/0.1.5.md b/docs/docs/releases/0.1.5.md
@@ -24,7 +24,7 @@ Refer to the [build documentation](../build/build.md#overdue-builds) for more in
 
 ### Stock Item Expiry
 
-[#1202](https://github.com/inventree/InvenTree/pull/1202) introduces the concept of an *Expiry Date* for Stock Items. For further information, refer to the [expiry documentation](../../stock/expiry).
+[#1202](https://github.com/inventree/InvenTree/pull/1202) introduces the concept of an *Expiry Date* for Stock Items. For further information, refer to the [expiry documentation](../stock/expiry.md).
 
 ### Stock Ownership
 

diff --git a/docs/docs/releases/0.2.1.md b/docs/docs/releases/0.2.1.md
@@ -14,7 +14,7 @@ title: Release 0.2.1
 
 !!! warning "Configuration Required"
     Refer to the [email configuration
-    options](../../start/config/#email-settings).
+    options](../start/config.md#email-settings).
 
 ### Manufacturer Parts
 

diff --git a/docs/docs/releases/0.6.0.md b/docs/docs/releases/0.6.0.md
@@ -54,7 +54,7 @@ PR [#2119](https://github.com/inventree/InvenTree/pull/2119) adds the ability to
 
 ### SSO Support
 
-PR [#2017](https://github.com/inventree/InvenTree/pull/2017) adds support for SSO (single sign on) authentication. SSO integration requires configuration by the system administrator. Refer to the [SSO documentation](../settings/sso) for further information.
+PR [#2017](https://github.com/inventree/InvenTree/pull/2017) adds support for SSO (single sign on) authentication. SSO integration requires configuration by the system administrator. Refer to the [SSO documentation](../settings/SSO.md) for further information.
 
 ### BOM Substitution
 
@@ -74,7 +74,7 @@ PR [#2208](https://github.com/inventree/InvenTree/pull/2208) provides notificati
 
 ### MFA Support
 
-PR [#2221](https://github.com/inventree/InvenTree/pull/2221) adds support for MFA (multi factor authentication). This enables admins to require all users to enable MFA as a second auth step. Refer to the [documentation](../settings/mfa) for further information.
+PR [#2221](https://github.com/inventree/InvenTree/pull/2221) adds support for MFA (multi factor authentication). This enables admins to require all users to enable MFA as a second auth step. Refer to the [documentation](../settings/MFA.md) for further information.
 ### Stock Item Forms
 
 PR [#2198](https://github.com/inventree/InvenTree/pull/2198) provides a major refactor of stock item forms, for creating and editing stock items. These forms have been migrated to the REST API, providing a much more responsive user experience.