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
7164bee
commit abf64f1
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 try 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: | ||
| [Create a new project](../../../user/projects/create.md) | ||
| 1. [Create new tool model](../../../user/projects/models/create.md), select | ||
| Capella as tool and the version you want to use. | ||
| 1. Make sure that right version and nature is selected! If they are not | ||
| configured, the following steps will not work! | ||
| 1. [Link the TeamForCapella repository to the new model](../project-integration/project-integration.md) | ||
| if not already done. | ||
| 1. [Link a Git repository](../../../user/projects/models/create.md#step-31-link-existing-git-repository) | ||
| if not already done. It's required for the backup pipelines as well as for | ||
| the diagram cache and model complexity badge. | ||
| 1. [Spawn a new persistent session](../../../user/sessions/request.md) with the | ||
| tool Capella and the version that you chose before. | ||
| 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,117 @@ | ||
| <!-- | ||
| ~ 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. | ||
|
|
||
| <!-- prettier-ignore --> | ||
| !!! 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 | ||
|
|
||
| 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) | ||
|
|
||
| <!-- prettier-ignore --> | ||
| !!! 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 above. 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 | ||
|
|
||
| ## 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`, insert | ||
| a short description and pick a date until when the token should be valid. | ||
|
|
||
| <!-- prettier-ignore --> | ||
| !!! 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 token have the same scope as the user who created it. It is | ||
| therefore important that you never pass on the token and treat it responsibly. | ||
| All requests are made in the name of the user who issued the token and are | ||
| logged accordingly. If you feel that the token has been lost, revoke it | ||
| immediately and inform the Systems Engineering Toolchain team. | ||
|
|
||
| ### Revoke a PAT | ||
|
|
||
| In order to revoke a token go to `Menu` > `Token`. There you can see a list of | ||
| all tokens that belong to your user. 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 for basic authentication against the API. Use the token | ||
| as password and your username as username. | ||
|
|
||
| #### Example with Python | ||
|
|
||
| ```py | ||
| import requests | ||
|
|
||
| base_url = "example.com" # Replace with your base URL | ||
|
|
||
| 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://[baseURL]/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 | ||
| model = capellambse.model.MelodyModel( | ||
| path="<path to the model on your machine>", | ||
| diagram_cache={ | ||
| "path": "https://<your backend url>/api/v1/projects/<your project slug>/models/<your model slug>/diagrams/%s", | ||
| "username": "<username>", | ||
| "password": "<your PAT>", | ||
| } | ||
| ) | ||
| ``` | ||
|
|
||
| Having created a model like that you can e.g. with `model.diagrams[0]` get the | ||
| first diagram. |
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,11 @@ | ||
| --- | ||
| template: redirect.html | ||
| location: /api/docs/openapi.json | ||
| title: OpenAPI Specification (JSON) | ||
| icon: octicons/link-external-16 | ||
| --- | ||
|
|
||
| <!-- | ||
| ~ SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors | ||
| ~ SPDX-License-Identifier: Apache-2.0 | ||
| --> |
Oops, something went wrong.