Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add example to trg 1.08 #1103

Merged
merged 2 commits into from
Dec 13, 2024
Merged

docs: add example to trg 1.08 #1103

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a777384
Added example to TRG 1.08
ClosedSourcerer Dec 2, 2024
8fadd67
wording
ClosedSourcerer Dec 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions docs/release/trg-1/trg-1-08.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,3 +25,35 @@ Interface documentation is crucial to interact with components. It fundamentally
- consider functional and non-functional commitments of each interface
- make sure that the context of a request is understandable, like the sequence of API calls
- anchor a link to your Interface documentation within your `README.md` (see [TRG 1.01](https://eclipse-tractusx.github.io/docs/release/trg-1/trg-1-1))

## Example

For APIs referenced by KITs in the [Eclipse Tractus-X GitHub.io repository](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) the following applies:

- Create a folder with a name that corresponds to your KIT [here](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/tree/main/openApi)
- Place your .yaml files inside that folder
- Edit [.tractusx](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/main/.tractusx) and reference the desired .yaml files in the `openApiSpecs:` section
- The .yaml files will be ingested and hosted by the [API-hub](https://eclipse-tractusx.github.io/api-hub/eclipse-tractusx.github.io)
- The Api-hub will also generate a swagger-UI from the .yaml files
- Link the swagger-ui or .yaml files hosted by the API-hub
- The folder structure generated by the API-hub is derived from the `version` as defined by the .yaml file and the filename itself

Example [.tractusx](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/main/.tractusx) file ingested by the API-hub

```text
product: "eclipse-tractusx.github.io"
leadingRepository: "https://github.com/eclipse-tractusx/eclipse-tractusx.github.io"
repoCategory: "support"
repositories:
- name: "eclipse-tractusx.github.io"
usage: "Eclipse-tractusx website repository"
url: "https://github.com/eclipse-tractusx/eclipse-tractusx.github.io"
openApiSpecs:
- "https://raw.githubusercontent.com/eclipse-tractusx/eclipse-tractusx.github.io/main/openApi/dt/kit_digital-twin-kit-submodel-api_openAPI.yaml"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the future one could also think of creating tags in the website repo at every release to version the api specs (as far as I understood, currently only the kits documentation is "versioned" via a folder structure).

Suggested change
- "https://raw.githubusercontent.com/eclipse-tractusx/eclipse-tractusx.github.io/main/openApi/dt/kit_digital-twin-kit-submodel-api_openAPI.yaml"
- "https://raw.githubusercontent.com/eclipse-tractusx/eclipse-tractusx.github.io/refs/tags/R25.03/openApi/dt/kit_digital-twin-kit-submodel-api_openAPI.yaml"
- "https://raw.githubusercontent.com/eclipse-tractusx/eclipse-tractusx.github.io/refs/tags/R24.12/openApi/dt/kit_digital-twin-kit-submodel-api_openAPI.yaml"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the review.
I agree that versioning the API references is a sensible and the only precise approach.

Afaik, currently all KITs do get "promoted" into the new release, even if there are 0 changes.
With the tagged approach updating the tags for the APIs would become a regular maintanance task that has to be performed every release.

As for the suggested changes:
Since tagging is currently not in place, integrating them would move the example away from the current reality and I want the example to reflect the current reality and not a, for now, unrealised utopia :)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I used the suggested changed function just to make the possible future enhancement proposal more understandable and I didn't expect them to be implemented as part of this PR.

```

Example [Swagger-UI](https://eclipse-tractusx.github.io/api-hub/eclipse-tractusx.github.io/kit-digital-twin-kit-submodel-api-V3.0.1_SSP-003/swagger-ui/) generated by the API-hub

Example [.yaml](https://eclipse-tractusx.github.io/api-hub/eclipse-tractusx.github.io/kit-digital-twin-kit-submodel-api-V3.0.1_SSP-003/kit_digital-twin-kit-submodel-api_openAPI.yaml) file hosted by the API-hub

Example folder structure generated by the API-hub: `/api-hub/eclipse-tractusx.github.io/kit-digital-twin-kit-submodel-api-V3.0.1_SSP-003/`
Loading