TRG 1.08 - Interface documentation (APIs)

Status	Created	Post-History
Active	01-Aug-2024
Draft	21-Mar-2024	Transferred from Release Acceptance Criteria into TRG

Why

Interface documentation is crucial to interact with components. It fundamentally enables others to consume your APIs.

Description

• The interface documentation should be either stored in the folder /docs/api as openAPI.yaml or referenced in the .tractusx meta file as reachable document (like GitHub release asset) through the openApiSpecs key
  • It must be in the OpenAPI standard
    • It must be at least version 2
  • It must contain all interfaces
  • It must be up-to-date for the latest released component version

Best Practice

• 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)

Example

For APIs referenced by KITs in the Eclipse Tractus-X GitHub.io repository the following applies:

• Create a folder with a name that corresponds to your KIT here
• Place your .yaml files inside that folder
• Edit .tractusx and reference the desired .yaml files in the openApiSpecs: section
• The .yaml files will be ingested and hosted by the API-hub
• 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 file ingested by the API-hub

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"

Example Swagger-UI generated by the API-hub

Example .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/