diff --git a/docs/.gitignore b/docs/.gitignore index ecbeb1b0ab..ea8649cfa3 100644 --- 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/schema.md b/docs/docs/api/schema.md deleted file mode 100644 index 6c962e2df2..0000000000 --- a/docs/docs/api/schema.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: 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. - -## Schema File - --- TODO -- download - -## Schama Spcecification - -[OAD(./docs/api.yml)] diff --git a/docs/docs/api/schema/auth.md b/docs/docs/api/schema/auth.md new file mode 100644 index 0000000000..42bce31242 --- /dev/null +++ b/docs/docs/api/schema/auth.md @@ -0,0 +1,8 @@ + + --- + title: Authorization and Authentication API Schema + --- + + The *Authorization and Authentication* 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 new file mode 100644 index 0000000000..a905832189 --- /dev/null +++ b/docs/docs/api/schema/background-task.md @@ -0,0 +1,8 @@ + + --- + title: Background Task Management API Schema + --- + + The *Background Task Management* 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 new file mode 100644 index 0000000000..a97599a5ed --- /dev/null +++ b/docs/docs/api/schema/barcode.md @@ -0,0 +1,8 @@ + + --- + title: Barcode Scanning API Schema + --- + + The *Barcode Scanning* 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 new file mode 100644 index 0000000000..ad6646793d --- /dev/null +++ b/docs/docs/api/schema/bom.md @@ -0,0 +1,8 @@ + + --- + title: Bill of Materials API Schema + --- + + The *Bill of Materials* 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 new file mode 100644 index 0000000000..c3cb3862cd --- /dev/null +++ b/docs/docs/api/schema/build.md @@ -0,0 +1,8 @@ + + --- + title: Build Order Management API Schema + --- + + The *Build Order Management* 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 new file mode 100644 index 0000000000..f4bd3623c1 --- /dev/null +++ b/docs/docs/api/schema/company.md @@ -0,0 +1,8 @@ + + --- + title: Company Management API Schema + --- + + The *Company Management* 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 new file mode 100644 index 0000000000..c5baa9fae9 --- /dev/null +++ b/docs/docs/api/schema/general.md @@ -0,0 +1,8 @@ + + --- + title: General API Endpoints API Schema + --- + + The *General API Endpoints* 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 new file mode 100644 index 0000000000..ab3631e16a --- /dev/null +++ b/docs/docs/api/schema/label.md @@ -0,0 +1,8 @@ + + --- + title: Label Printing API Schema + --- + + The *Label Printing* API schema is documented below. + + [OAD(./docs/docs/api/schema/label.yml)] diff --git a/docs/docs/api/schema/order.md b/docs/docs/api/schema/order.md new file mode 100644 index 0000000000..75cd061514 --- /dev/null +++ b/docs/docs/api/schema/order.md @@ -0,0 +1,8 @@ + + --- + title: External Order Management API Schema + --- + + The *External Order Management* 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 new file mode 100644 index 0000000000..8a563bd38d --- /dev/null +++ b/docs/docs/api/schema/part.md @@ -0,0 +1,8 @@ + + --- + title: Parts and Part Categories API Schema + --- + + The *Parts and Part Categories* 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 new file mode 100644 index 0000000000..e7305f3e1b --- /dev/null +++ b/docs/docs/api/schema/plugins.md @@ -0,0 +1,8 @@ + + --- + title: Plugin Functionality API Schema + --- + + The *Plugin Functionality* 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 new file mode 100644 index 0000000000..b24dc90fb7 --- /dev/null +++ b/docs/docs/api/schema/report.md @@ -0,0 +1,8 @@ + + --- + title: Report Generation API Schema + --- + + The *Report Generation* API schema is documented below. + + [OAD(./docs/docs/api/schema/report.yml)] diff --git a/docs/docs/api/schema/schema.md b/docs/docs/api/schema/schema.md new file mode 100644 index 0000000000..c6f49ecee9 --- /dev/null +++ b/docs/docs/api/schema/schema.md @@ -0,0 +1,37 @@ + + --- + 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: `166` + + ## 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 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/settings.md b/docs/docs/api/schema/settings.md new file mode 100644 index 0000000000..0f77c0149b --- /dev/null +++ b/docs/docs/api/schema/settings.md @@ -0,0 +1,8 @@ + + --- + title: Settings Management API Schema + --- + + The *Settings Management* 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 new file mode 100644 index 0000000000..b354b516a7 --- /dev/null +++ b/docs/docs/api/schema/stock.md @@ -0,0 +1,8 @@ + + --- + title: Stock and Stock Locations API Schema + --- + + The *Stock and Stock Locations* 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 new file mode 100644 index 0000000000..0b355b4e6c --- /dev/null +++ b/docs/docs/api/schema/user.md @@ -0,0 +1,8 @@ + + --- + title: User Management API Schema + --- + + The *User Management* API schema is documented below. + + [OAD(./docs/docs/api/schema/user.yml)] diff --git a/docs/exctract_schema.py b/docs/exctract_schema.py index 66b9a6187a..a5f683ae7c 100644 --- a/docs/exctract_schema.py +++ b/docs/exctract_schema.py @@ -11,22 +11,22 @@ OUTPUT_DIR = './docs/api/schema/' GENERAL_PATH = 'general' # List of special paths we want to split out -SPECIAL_PATHS = [ - 'auth', - 'background-task', - 'barcode', - 'bom', - 'build', - 'company', - 'label', - 'order', - 'part', - 'plugins', - 'report', - 'settings', - 'stock', - 'user', -] +SPECIAL_PATHS = { + 'auth': 'Authorization and Authentication', + 'background-task': 'Background Task Management', + 'barcode': 'Barcode Scanning', + 'bom': 'Bill of Materials', + 'build': 'Build Order Management', + 'company': 'Company Management', + 'label': 'Label Printing', + 'order': 'External Order Management', + 'part': 'Parts and Part Categories', + 'plugins': 'Plugin Functionality', + 'report': 'Report Generation', + 'settings': 'Settings Management', + 'stock': 'Stock and Stock Locations', + 'user': 'User Management', +} def top_level_path(path: str) -> str: @@ -43,12 +43,53 @@ def top_level_path(path: str) -> str: key = path.split('/')[1] - if key in SPECIAL_PATHS: + if key in SPECIAL_PATHS.keys(): return key return GENERAL_PATH +def generate_index_file(version: str): + """Generate the index file for the API schema.""" + output = f""" + --- + 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: `{version}` + + ## 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 | + | --- | --- | + """ + + for key, value in SPECIAL_PATHS.items(): + output += f'| [{value}](./schema/{key}.md) | {value} |\n' + + output += '| [General](./schema/general.md) | General API endpoints |\n' + + output += '\n' + + output_file = os.path.join(os.path.dirname(__file__), OUTPUT_DIR, 'schema.md') + + print('Writing index file to:', output_file) + + with open(output_file, 'w') as f: + f.write(output) + + def parse_api_file(filename: str): """Parse the input API file, and split into smaller sections. @@ -88,6 +129,9 @@ def parse_api_file(filename: str): with open(output_file, 'w') as f: yaml.dump(output, f) + # Finally, generate an index file for the API schema + generate_index_file(data['info']['version']) + if __name__ == '__main__': parser = argparse.ArgumentParser(description=__doc__) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index b6f99dd673..5978aaab7a 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -183,7 +183,7 @@ nav: - Extend: - InvenTree API: - Overview: api/api.md - - Schema: api/schema.md + - API Schema: api/schema.md - Model Metadata: api/metadata.md - Download Data: api/download.md - Bulk Delete: api/bulk_delete.md