search

eclipse-tractusx / eclipse-tractusx.github.io

https://eclipse-tractusx.github.io/
Apache License 2.0
29 stars 87 forks source link

[KITs] Remove API Plug-In in KITs #970

Open danielmiehle opened 3 months ago

danielmiehle commented 3 months ago

Description

We will discontinue the use of the openAPI Plugin in the KITs to ensure the upgradeability of Docusaurus to version 3.0. We ask you to make the changes in your KITs as soon as possible so that we can use resources from the consortium to update Docusaurus.

Please note the following guidance:

Acceptance Criteria -- Update from Tomasz:

  1. KITs API spec would follow configuration method, meaning you add each OpenAPI spec in the .tractusx metadata file as TRG states. No need to move files to /docs/api folder in repo.

  2. KITs OpenAPI spec filenames need to follow special naming convention “kit_nameofthekitopenAPI.yaml”. The only part which you change is “nameofthekit”, you change it as you like the only caveat is to not use “” underscore in that name.

  3. Your Swagger UI docs would be available at following URL: [https://eclipse-tractusx.github.io/api-hub/repo/kit-nameofthekit-version/swagger-ui/]

  4. Optional: For short APIs: Integrate your API in-line as a code block, for example: Agent KIT

Additional Information

After evaluation, the Swagger Hub does not fit our needs, so a new API Hub is to be set up:

https://github.com/eclipse-tractusx/api-hub https://github.com/eclipse-tractusx/sig-infra/issues/376

Task List

We have identified the following KITs that are affected by the change.

danielmiehle commented 3 months ago

@SebastianBezold @stephanbcbauer @jSchuetz88 :

Can you please review the issue and complement if necessary. Thanks!

nhaenis commented 3 months ago

AC: Mandatory: Link your yaml file in an appropriate location in your development view .md file

What should such a link look like? Would it just be [Find here](./openApi/dcm/myYaml.yaml) or can someone please provide an example of this? Thank you very much

ClosedSourcerer commented 3 months ago

https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/pull/969

DCM added just this for the KIT 24.08 Release. See PR above.

arnoweiss commented 2 months ago

What does

without business domain (!)

mean? @danielmiehle

danielmiehle commented 2 months ago

Hi @arnoweiss ,

in the Catena-X Consoritum, we have assigned use cases to 3 business domains (e.g. sustainability, resiliency). I would no longer make this assignment in future.

danielmiehle commented 2 months ago

Please see updated guidance:

  1. KITs API spec would follow configuration method, meaning you add each OpenAPI spec in the .tractusx metadata file as TRG states. No need to move files to /docs/api folder in repo.
  2. KITs OpenAPI spec filenames need to follow special naming convention “kit_nameofthekitopenAPI.yaml”. The only part which you change is “nameofthekit”, you change it as you like the only caveat is to not use “” underscore in that name.
  3. Your Swagger UI docs would be available at following URL: [https://eclipse-tractusx.github.io/api-hub/repo/kit-nameofthekit-version/swagger-ui/]
stephanbcbauer commented 2 months ago

@danielmiehle isn't EDC missing in this list? Was there a list to follow?

stephanbcbauer commented 2 months ago

@danielmiehle isn't EDC missing in this list? Was there a list to follow?

no its not missing :)

danielmiehle commented 2 months ago

@stephanbcbauer : Could not find any API plug-in the connector kit. Can you please provide a link?

arnoweiss commented 2 months ago

So there's no central collection anymore but the swagger-pages are built from the reference implementations' repositories?

danielmiehle commented 2 months ago

@tomaszbarwicki: Can you please help and explain how the mechanism exactly works? Thanks!

tomaszbarwicki commented 2 months ago

So there's no central collection anymore but the swagger-pages are built from the reference implementations' repositories?

Hi @arnoweiss, @danielmiehle,

There is central collection at api-hub. You can visit currently hosted Swagger UI generated docs at https://eclipse-tractusx.github.io/api-hub/. Recently TRG 1.8 was published describing two options of getting your OpenAPI specs based docs hosted on api-hub github pages. The guidance above is strictly related to KITs APIs which follow slightly different concept in term of specs storage since there is no separate repos for them hence required an enhacement to current automation to generate and host swagger ui docs at api-hub as well.

@Siegfriedk it might be worth adding the KITs guidance to TRG..