forked from NVIDIAGameWorks/toolkit-remix
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'dev/ptrottier/rest_api_docs' into 'main'
Added REST API documentation See merge request lightspeedrtx/lightspeed-kit!725
- Loading branch information
Showing
26 changed files
with
602 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,62 @@ | ||
| # REST API | ||
|
|
||
| The RTX Remix REST API allows users to send and receive information to and from the Toolkit respectively, as well as | ||
| trigger actions in the Toolkit (such as starting the ingestion of a given file, etc.) via HTTP requests. | ||
|
|
||
| ## Finding the Documentation | ||
|
|
||
| The documentation for the Remix Toolkit REST API can be accessed in two different ways: **Live**, and **Static**. | ||
|
|
||
| To view the list of endpoints exposed by the RTX Remix Toolkit REST API, follow these instructions: | ||
|
|
||
| ### Live Documentation: | ||
|
|
||
| The live documentation is generated when the Remix Toolkit starts up and gives the ability to test the various endpoints | ||
| seamlessly directly from the documentation itself. | ||
|
|
||
| 1) Start the Remix Toolkit | ||
| 2) Visit the following website in your web browser: [`http://127.0.0.1:8011/docs#/`](http://127.0.0.1:8011/docs#/) or [`http://localhost:8011/docs#/`](http://localhost:8011/docs#/) | ||
|
|
||
| **_NOTE: The 2 websites are equivalent and can be used interchangeably_** | ||
|
|
||
| ### Static Documentation: | ||
|
|
||
| The static documentation doesn't require the Remix Toolkit to be installed and running. | ||
|
|
||
| 1) Visit the [`API documentation page`](./remix-toolkitinterface-restapi-docs.html) | ||
|
|
||
| ## Understanding the Documentation | ||
|
|
||
| When opening the documentation website, you will be greeted with a list of available endpoints. Every row is a unique | ||
| endpoint (HTTP Verb + URL) with a unique purpose. | ||
|
|
||
| Clicking on said row will reveal more information about the endpoint, including the expected path parameters, | ||
| query parameters, request body, etc. | ||
|
|
||
|  | ||
|
|
||
| ### Endpoint Versioning | ||
|
|
||
| The Remix Toolkit REST API uses a versioning header to version every endpoint available individually. A dropdown with | ||
| the list of available endpoint version headers can be found in the endpoint details with the `Request body` text or | ||
| within the `Successful Response` sub-section of the `Responses` section. The header should have the following format: | ||
|
|
||
| ``` | ||
| application/lightspeed.remix.service+json; version=1.0 | ||
| ``` | ||
|
|
||
| ## Testing the Endpoints | ||
|
|
||
| Endpoints can be easily tested directly in the documentation. To do so, follow these instructions: | ||
|
|
||
| 1) Expand the endpoint your would like to test | ||
| 2) Click the `Try it now` button | ||
| 3) Fill in any required parameters/body | ||
| 4) Click the `Execute` button | ||
| 5) In the `Responses` section, look for the `Server response` subsection. | ||
| 6) You should see a response `Code` and `Details` for the request you sent in the previous step. | ||
|
|
||
|  | ||
|
|
||
| *** | ||
| <sub> Need to leave feedback about the RTX Remix Documentation? [Click here](https://github.com/NVIDIAGameWorks/rtx-remix/issues/new?assignees=nvdamien&labels=documentation%2Cfeedback%2Ctriage&projects=&template=documentation_feedback.yml&title=%5BDocumentation+feedback%5D%3A+) <sub> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
62 changes: 62 additions & 0 deletions
62
source/apps/omni.flux.app.service.documentation_cli_generator.kit
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,62 @@ | ||
| [package] | ||
| version = "1.0.0" | ||
| category = "Application" | ||
| title = "Flux Service Documentation Generation App" | ||
| description = "App used to generate the shortcut of the Service Documentation Generation CLI" | ||
| authors = ["Pierre-Olivier Trottier <ptrottier@nvidia.com>"] | ||
| repository = "https://gitlab-master.nvidia.com/lightspeedrtx/lightspeed-kit" | ||
| keywords = ["omni", "flux", "app", "service", "documentation", "CLI", "Generator"] | ||
| changelog = """ | ||
| # Changelog | ||
| The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). | ||
|
|
||
| ## [1.0.0] | ||
| ### Added | ||
| - Created | ||
| """ | ||
| readme = """ | ||
| # Omniverse Flux Service Documentation Generation | ||
|
|
||
| A tool to generate static documentation from Kit microservices | ||
| """ | ||
|
|
||
| [dependencies] | ||
| "omni.flux.service.documentation" = {} | ||
|
|
||
| [settings.app.window] | ||
| title = "Flux Service Documentation Generation App" | ||
|
|
||
| [settings] | ||
| # Basic Kit App | ||
| ################################ | ||
| app.versionFile = "${app}/../../../VERSION" | ||
| app.fastShutdown = true | ||
|
|
||
| # Register extension folder from this repo in kit | ||
| [settings.app.exts] | ||
| folders.'++' = ["${app}/../../../exts", "${app}/../../../extscache", "${app}/../exts", "${app}/../extscache", "${kit}/../exts", "${kit}/../extscache"] | ||
|
|
||
| [[test]] | ||
| args = [ | ||
| "--/app/window/width=480", | ||
| "--/app/window/height=480", | ||
| ] | ||
|
|
||
| dependencies = [ | ||
| "omni.flux.tests.dependencies", | ||
| ] | ||
|
|
||
| ######################################################################################################################## | ||
| # BEGIN GENERATED PART (Remove from 'BEGIN' to 'END' to regenerate) | ||
| ######################################################################################################################## | ||
|
|
||
| # Kit SDK Version: 106.0.0+release.118399.fcefe91f.gl | ||
|
|
||
| # Version lock for all dependencies: | ||
| [settings.app.exts] | ||
| enabled = [ | ||
| ] | ||
|
|
||
| ######################################################################################################################## | ||
| # END GENERATED PART | ||
| ######################################################################################################################## |
42 changes: 42 additions & 0 deletions
42
...tensions/omni.flux.service.documentation/apps/omni.flux.app.service.documentation_cli.kit
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| [package] | ||
| title = "Flux Service Documentation Generation App" | ||
|
|
||
| # That makes it browsable in UI with "experience" filter | ||
| keywords = ["app"] | ||
|
|
||
| [dependencies] | ||
| "omni.flux.service.documentation" = {} | ||
|
|
||
| [settings.app.window] | ||
| title = "Flux Service Documentation Generation App" | ||
|
|
||
| [settings] | ||
| # Basic Kit App | ||
| ################################ | ||
| app.versionFile = "${app}/../../../VERSION" | ||
| app.fastShutdown = true | ||
|
|
||
| # Register extension folder from this repo in kit | ||
| [settings.app.exts] | ||
| folders.'++' = ["${app}/../../../exts", "${app}/../../../extscache", "${app}/../exts", "${app}/../extscache", "${kit}/../exts", "${kit}/../extscache"] | ||
|
|
||
| [[test]] | ||
| args = [ | ||
| "--/app/window/width=480", | ||
| "--/app/window/height=480", | ||
| ] | ||
|
|
||
| ######################################################################################################################## | ||
| # BEGIN GENERATED PART (Remove from 'BEGIN' to 'END' to regenerate) | ||
| ######################################################################################################################## | ||
|
|
||
| # Kit SDK Version: 106.0.0+release.118399.fcefe91f.gl | ||
|
|
||
| # Version lock for all dependencies: | ||
| [settings.app.exts] | ||
| enabled = [ | ||
| ] | ||
|
|
||
| ######################################################################################################################## | ||
| # END GENERATED PART | ||
| ######################################################################################################################## |
10 changes: 10 additions & 0 deletions
10
source/extensions/omni.flux.service.documentation/bin/cli.bat
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| @echo off | ||
|
|
||
| call "%~dp0..\..\..\dev\tools\packman\python" %~dp0cli.py %* | ||
| if %errorlevel% neq 0 ( goto Error ) | ||
|
|
||
| :Success | ||
| exit /b 0 | ||
|
|
||
| :Error | ||
| exit /b %errorlevel% |
80 changes: 80 additions & 0 deletions
80
source/extensions/omni.flux.service.documentation/bin/cli.py
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,80 @@ | ||
| """ | ||
| * SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved. | ||
| * SPDX-License-Identifier: Apache-2.0 | ||
| * | ||
| * Licensed under the Apache License, Version 2.0 (the "License"); | ||
| * you may not use this file except in compliance with the License. | ||
| * You may obtain a copy of the License at | ||
| * | ||
| * https://www.apache.org/licenses/LICENSE-2.0 | ||
| * | ||
| * Unless required by applicable law or agreed to in writing, software | ||
| * distributed under the License is distributed on an "AS IS" BASIS, | ||
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| * See the License for the specific language governing permissions and | ||
| * limitations under the License. | ||
| """ | ||
|
|
||
| import argparse | ||
| import pathlib | ||
| import platform | ||
| import subprocess | ||
|
|
||
|
|
||
| def main(): | ||
| example = r""" | ||
| Example: | ||
| cli.bat -o "{kit}\..\..\..\docs\flux\latest\service-documentation.html" -e omni.flux.service.factory | ||
| """ # noqa | ||
|
|
||
| parser = argparse.ArgumentParser( | ||
| description="Run the service documentation generation in command line.", | ||
| epilog=example, | ||
| formatter_class=argparse.RawTextHelpFormatter, | ||
| ) | ||
| parser.add_argument("-o", "--output", type=str, help="The output HTML file path", required=True) | ||
| parser.add_argument( | ||
| "-e", | ||
| "--enable", | ||
| help="Name(s) of the Kit extension(s) plugin we want to use", | ||
| nargs="+", | ||
| type=str, | ||
| required=True, | ||
| ) | ||
| parser.add_argument( | ||
| "-x", "--extra-args", help="Any extra arguments to pass to Kit", action="append", type=str, required=False | ||
| ) | ||
| args = parser.parse_args() | ||
|
|
||
| if pathlib.Path(args.output).suffix.lower() != ".html": | ||
| raise ValueError("The output file must be an HTML file. (.html)") | ||
|
|
||
| root_dir = pathlib.Path(__file__).parent.parent.parent.parent | ||
|
|
||
| cmd = [ | ||
| str(root_dir.joinpath("kit", "kit.exe" if platform.system() == "Windows" else "kit")), | ||
| str(pathlib.Path(__file__).parent.parent.joinpath("apps", "omni.flux.app.service.documentation_cli.kit")), | ||
| ] | ||
| for ext in args.enable: | ||
| cmd.extend(["--enable", ext]) | ||
|
|
||
| for arg in args.extra_args or []: | ||
| cmd.extend([arg]) | ||
|
|
||
| cmd.append("--no-window") | ||
| exec_cmd = f"{pathlib.Path(__file__).parent.parent.joinpath('omni', 'flux', 'service', 'documentation', 'cli.py')}" # noqa E501 | ||
| exec_cmd += f' -o "{args.output}"' | ||
| cmd.extend(["--exec", exec_cmd]) | ||
|
|
||
| print(" ".join(cmd)) | ||
| with subprocess.Popen(cmd, stdout=subprocess.PIPE, bufsize=1, universal_newlines=True) as p: | ||
| for line in p.stdout: | ||
| print(line, end="") # process line here | ||
|
|
||
| if p.returncode != 0: | ||
| raise subprocess.CalledProcessError(p.returncode, p.args) | ||
|
|
||
|
|
||
| if __name__ == "__main__": | ||
| main() |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| #!/bin/bash | ||
|
|
||
| set -e | ||
|
|
||
| SCRIPT_DIR=$(dirname ${BASH_SOURCE}) | ||
| cd "$SCRIPT_DIR" | ||
|
|
||
| exec "$SCRIPT_DIR/../../../dev/tools/packman/python.sh" cli.py $@ |
Oops, something went wrong.