Switch from SwaggerHub to GitHub-rendered OpenAPI Files#633
Conversation
Replace all SwaggerHub references with GitHub Pages Swagger UI links and convert OpenAPI $ref to relative paths for self-contained specs. Changes: 1. Documentation links (44 URLs): - Replace app.swaggerhub.com with industrialdigitaltwin.io/aas-specs-api - Point to GitHub Pages Swagger UI renderer - Files: general.adoc, http-rest-api.adoc, service-specifications-and-profiles.adoc 2. OpenAPI $ref references (5,545): - Convert absolute SwaggerHub API URLs to relative paths - Pattern: https://api.swaggerhub.com/.../V3.2.0#/... → ../SchemaName/openapi.yaml#/... - Makes specs self-contained and independent of external services - Files: All 35 service specification YAML files + Part2-API-Schemas Benefits: - No dependency on SwaggerHub infrastructure - OpenAPI parsers can resolve relative paths natively - Faster resolution (local files) - Standard OpenAPI practice - Specs remain fully functional for validation and code generation BREAKING CHANGE: External tools referencing SwaggerHub URLs must update to use GitHub Pages or raw GitHub URLs for the YAML files.
sebbader-sap
requested review from
BirgitBoss,
alexgordtop,
aorzelskiGH,
danielporta,
g1zzm0,
mjacoby,
waltersve and
zrgt
as code owners
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
…b-to-github-rendered-openapi
aaronzi
left a comment
aaronzi
left a comment
There was a problem hiding this comment.
Looks mostly good. I think you have missed the Entire-API-Collection/V3.2.yaml. Was that intentional?
BirgitBoss
left a comment
BirgitBoss
left a comment
There was a problem hiding this comment.
'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0 consistently changed to ../Part2-API-Schemas/openapi.yaml#
BirgitBoss
left a comment
BirgitBoss
left a comment
There was a problem hiding this comment.
Sorry, I just saw that Aaron had some good points that probably are not yet resolved?
Co-authored-by: Aaron Zielstorff <aaron.zielstorff@iese.fraunhofer.de>
Co-authored-by: Aaron Zielstorff <aaron.zielstorff@iese.fraunhofer.de>
- Resolve conflicts by converting SwaggerHub URLs to relative paths - Include new parameters (AssetIds, CreatedFrom, UpdatedFrom) from base branch - Merge changelog entries from both branches
- Update Entire-API-Collection/V3.2.yaml: convert all SwaggerHub URLs to relative paths - Update README.md: remove obsolete SwaggerHub synchronization references - Clarify that GitHub Pages is now the primary hosting platform - Remove SwaggerHub GitHub Synchronization section
|
@aaronzi & @BirgitBoss please have a look again. |
aaronzi
left a comment
aaronzi
left a comment
There was a problem hiding this comment.
I think there are still problems. Sorry for not taking the time to mark the respective parts and just dumping it like this:
general.adoc (line 306): the AAS service link is still malformed: V3.2_SSP-001).yaml, and the link text still says V3.1_SSP-001.
README.md (line 36) and http-rest-api.adoc (line 27): Part 1 links still target ./Part1-MetaModel-Schemas/openapi_3.2.yaml, but the branch only contains Part1-MetaModel-Schemas/openapi.yaml. The ./ also resolves under /docs/, unlike the working ../... links.
http-rest-api.adoc (line 32): Part 2 uses url=./Part2-API-Schemas/openapi.yaml, which likewise resolves under /docs/; other working links use ../Part2-API-Schemas/openapi.yaml.
general.adoc (line 286): still links to missing AssetAdministrationShellRepositoryServiceSpecification/V3.1_SSP-001.yaml.
general.adoc (line 305): the AASX link still has a stray closing ] after the URL.
git diff --check origin/IDTA-01002-3-2_working...HEAD still fails due to trailing whitespace in added YAML lines and extra blank lines at EOF in README.md.
Change from 'application/asset-administration-shell-package+xml' to 'application/aas+zip' to match the profile specifications (AssetAdministrationShellRepositoryServiceSpecification and SubmodelRepositoryServiceSpecification). Note: AASX File Server operations (PostAASXPackage, GetAASXByPackageId, etc.) correctly keep 'application/asset-administration-shell-package'.
Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com>
BirgitBoss
deleted the
SeBa/switch-from-swaggerhub-to-github-rendered-openapi
branch
4 participants
No description provided.