Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: Expose "API documentation" and restructure users docs
- A new section "API documentation" is added; PAT and authentication information is moved to the new section. - The new API documentation has a new Python example. - The new section has a link to the OpenAPI documentation, which in only accessible for running Collaboration Manager instances. - The OpenAPI documentation uses the correct auto-determined version now (before it was 0.1.0) - The Path to the documentation has changes, a prefix `/api/docs` was added, a redirect from the old `/docs` route is in place. - The "Tools" abstraction layer was removed in the tree. Instead, Capella & Jupyter have top level sections now. The goal is to increase visibility for the Capella section, which is frequently used. - "Flows" has been removed from the "Sessions" section; sessions will focus on tool independent topics; T4C flow is moved to "Capella" section - The Git workflow and API documentation are now mentioned in the Introduction of the user docs - For consistency, the Git workflow has it's own folder in the Capella section now (like T4C also has) - A full T4C setup guide was added, describing the creation of a T4C based project, from project creation to diagram cache setup. - Some general grammar & style improvements. - Old references to `Profile` are updated to `Menu` - Administrative T4C pages are moved to the admin section.
- Loading branch information
1 parent
54ba4a6
commit b3cae4d
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
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
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,21 @@ | ||
| <!-- | ||
| ~ SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors | ||
| ~ SPDX-License-Identifier: Apache-2.0 | ||
| --> | ||
|
|
||
| {% extends "main.html" %} {% block content %} | ||
| <h1>404 - Not found</h1> | ||
| <span> | ||
| If you are trying to access the API documentation: The API documentation is | ||
| not available in your current environment. It is only available via the | ||
| documentation of Collaboration Manager instances. It is not available on: | ||
|
|
||
| <ul> | ||
| <li>GitHub Pages</li> | ||
| <li>Local non-cluster development environments</li> | ||
| <li>ReadTheDocs</li> | ||
| </ul> | ||
|
|
||
| If you believe this is an error, please contact your system administrator. | ||
| </span> | ||
| {% endblock %} |
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
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,28 @@ | ||
| <!-- | ||
| ~ SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors | ||
| ~ SPDX-License-Identifier: Apache-2.0 | ||
| --> | ||
|
|
||
| This tutorial will guide you through the full setup of a new | ||
| TeamForCapella-based project in the Collaboration Manager. | ||
|
|
||
| 1. [Create a new project](../../../user/projects/create.md). | ||
| 1. [Create a new tool model in the project you created](../../../user/projects/models/create.md), | ||
| select Capella as tool and the version you want to use. | ||
| 1. [Link the TeamForCapella repository to the new model](../project-integration/project-integration.md) | ||
| if you have not done so already. | ||
| 1. [Link a Git repository](../../../user/projects/models/create.md#step-31-link-existing-git-repository) | ||
| if you have not done so already. It's required for the backup pipelines as | ||
| well as for the diagram cache and model complexity badge. | ||
| 1. Make sure that the right version and nature is configured for the tool | ||
| model! If they are not configured properly, you would not see the | ||
| TeamForCapella repository in the later export step. | ||
| 1. [Spawn a new persistent session](../../../user/sessions/request.md). Select | ||
| Capella as the tool, and select the previously selected tool version. | ||
| 1. Once Capella is open, create a new empty Capella project or import the | ||
| project that you want to initialize the TeamForCapella repository with. | ||
| 1. [Export the model to the new TeamForCapella repository](../../../user/tools/capella/teamforcapella/export/export-to-t4c.md). | ||
| 1. [Set up a backup pipeline](../../../user/projects/models/backups/setup.md). | ||
| 1. [Set up the model complexity badge](../../../user/projects/models/complexity_badge.md). | ||
| 1. [Set up the diagram cache](../../../user/projects/models/diagrams/setup_diagram_cache.md) | ||
| 1. Verify that everything works as expected. |
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
File renamed without changes
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes
File renamed without changes.
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
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,124 @@ | ||
| <!-- | ||
| ~ SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors | ||
| ~ SPDX-License-Identifier: Apache-2.0 | ||
| --> | ||
|
|
||
| # Automate tasks with our API | ||
|
|
||
| Our API is designed to be simple and easy to use. It is based on RESTful | ||
| principles and uses standard HTTP methods. This means that you can use the API | ||
| to automate tasks such as creating and managing projects, sessions, and users. | ||
|
|
||
| !!! warning | ||
|
|
||
| We try to keep the API as stable as possible, but we cannot guarantee that | ||
| it will not change in the future. If you are using the API, make sure to | ||
| check our [release notes](https://github.com/DSD-DBS/capella-collab-manager/releases) | ||
| for any breaking changes. | ||
|
|
||
| ## API Documentation | ||
|
|
||
| !!! note | ||
|
|
||
| **The API documentation is only available via the documentation of Collaboration | ||
| Manager instances**. Only in this case you'll be able to open the links below. | ||
| You'll see the API documentation matching the version of the Collaboration Manager | ||
| instance you are using. | ||
|
|
||
| It is not available on: | ||
|
|
||
| - GitHub Pages | ||
| - Local non-cluster development environments | ||
| - ReadTheDocs | ||
|
|
||
| Please use these links to access the API documentation: | ||
|
|
||
| - [:octicons-link-external-16: SwaggerUI](swagger.md) (Interactive SwaggerUI | ||
| documentation) | ||
| - [:octicons-link-external-16: ReDoc](redoc.md) (Interactive ReDoc | ||
| documentation) | ||
| - [:octicons-link-external-16: OpenAPI Specification, formerly Swagger Specification](openapi.md) | ||
| (JSON) | ||
|
|
||
| ## Authentication | ||
|
|
||
| To authenticate against the API you can use Personal Access Tokens (PAT). | ||
|
|
||
| ### PAT Creation | ||
|
|
||
| To create a personal access token (PAT) you can go to `Menu` > `Tokens`. Every | ||
| token requires a description and expiration date. | ||
|
|
||
| !!! info | ||
|
|
||
| The token which is generated will disappear after leaving the page. | ||
| Make sure you save it - you won't be able to access it again. | ||
|
|
||
| ### PAT Scope | ||
|
|
||
| Personal access tokens have the same scope as the user who created it. It is | ||
| therefore important that you do not share them with others or publish them. All | ||
| requests are made in the name of the user who issued the token and are logged | ||
| accordingly. If you lose, share, or publish a token you must revoke it | ||
| immediately and inform your system administrator team. | ||
|
|
||
| ### Revoke a PAT | ||
|
|
||
| In order to revoke a token go to `Menu` > `Token`. There you can see a list of | ||
| all tokens that are associated with your account. By clicking on the delete | ||
| button, you can delete a token, which will no longer be valid for | ||
| authentication. | ||
|
|
||
| ### PAT Usage | ||
|
|
||
| You can use the token in place of a password for basic authentication against | ||
| the API as in the following examples. | ||
|
|
||
| #### Example with Python | ||
|
|
||
| ```py | ||
| import requests | ||
|
|
||
| base_url = "example.com" # Replace with the base URL of your Collaboration Manager instance | ||
| username = "..." | ||
| token = "..." | ||
|
|
||
| requests.get( | ||
| f"https://{base_url}/api/v1/projects", | ||
| auth=(username, token) | ||
| ) | ||
| ``` | ||
|
|
||
| #### Example with cURL | ||
|
|
||
| With `cURL` you can use the following command to fetch the list of projects: | ||
|
|
||
| ```zsh | ||
| curl -u ${USERNAME}:${TOKEN} https://${BASE_URL}/api/v1/projects | ||
| ``` | ||
|
|
||
| #### Example with `capellambse` | ||
|
|
||
| Another example is working with the diagram cache of py-capellambse. The | ||
| implementation of the Capella modelling tool `capellambse` uses Python and lets | ||
| you read and write models. For more information have a look at the | ||
| [documentation](https://dsd-dbs.github.io/py-capellambse/) or the | ||
| [Github repository](https://github.com/DSD-DBS/py-capellambse). | ||
|
|
||
| ```python | ||
| import capellambse | ||
|
|
||
| base_url = "example.com" # Replace with the base URL of your Collaboration Manager instance | ||
| username = "..." | ||
| token = "..." | ||
| path_to_aird = "..." | ||
|
|
||
| model = capellambse.model.MelodyModel( | ||
| path=path_to_aird, | ||
| diagram_cache={ | ||
| "path": f"https://{base_url}/api/v1/projects/{project_slug}/models/{model_slug}/diagrams/%s", | ||
| "username": username, | ||
| "password": token, | ||
| } | ||
| ) | ||
| ``` |
Oops, something went wrong.