OpenAPI format support and generated documentation #43
Conversation
This file contains hidden or 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
There was a problem hiding this comment.
Pull Request Overview
This PR adds comprehensive support for the OpenAPI format and generates full API documentation for the Swift Package Registry. Key changes include converting OpenAPI documents to DocC symbol graphs, updating the CLI command options to reflect the new functionality, and adding/expanding multiple documentation files covering security, rate limiting, publishing, authentication, error handling, and API usage.
Reviewed Changes
Copilot reviewed 126 out of 132 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| Sources/Integration/OpenAPIDocCConverter.swift | Updated to use DocC.SymbolGraphGenerator for conversion. |
| Sources/Integration/Converter.swift | New converter function to transform OpenAPI docs to SymbolGraph. |
| Sources/CLI/main.swift | Renamed CLI command and refactored options for improved clarity. |
| RegistryAPI.docc/Tutorials/*.md (Security, RateLimiting, etc.) | New and updated documentation tutorials for various API topics. |
| RegistryAPI.docc/Resources/registry-custom.js | Added custom JavaScript for enhanced documentation styling. |
| Package.swift | Updated dependency URL for swift-docc-symbolkit. |
Files not reviewed (6)
- RegistryAPI.docc/Resources/css/custom.css: Language not supported
- docc-sample: Language not supported
- docs/.nojekyll: Language not supported
- docs/data/documentation/registry-api/authentication.json: Language not supported
- docs/data/documentation/registry-api/errorcodes.json: Language not supported
- docs/data/documentation/registry-api/gettingstarted.json: Language not supported
Comments suppressed due to low confidence (1)
Sources/CLI/main.swift:22
- [nitpick] The use of both 'output' and 'outputPath' options may be confusing. Consider consolidating them into a single, clearly named option to enhance clarity and maintainability.
@Option(name: .customLong("output-path"), help: "Alternative name for output directory")
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
| @@ -0,0 +1 @@ | |||
| {"hierarchy":{"paths":[["doc:\/\/com.example.RegistryAPI\/documentation\/RegistryAPI","doc:\/\/com.example.RegistryAPI\/documentation\/RegistryAPI\/__scope___name___version_","doc:\/\/com.example.RegistryAPI\/documentation\/RegistryAPI\/__scope___name___version_\/get"]]},"variants":[{"paths":["\/documentation\/registryapi\/__scope___name___version_.zip\/get\/401"],"traits":[{"interfaceLanguage":"openapi"}]}],"identifier":{"url":"doc:\/\/com.example.RegistryAPI\/documentation\/RegistryAPI\/__scope___name___version_.zip\/get\/401","interfaceLanguage":"openapi"},"kind":"symbol","schemaVersion":{"minor":3,"major":0,"patch":0},"metadata":{"externalID":"response:401","navigatorTitle":[{"kind":"text","text":"401 Response"}],"role":"symbol","title":"401 Response","symbolKind":"struct","roleHeading":"Response","modules":[{"name":"RegistryAPI"}]},"abstract":[{"text":"Referenced response","type":"text"}],"sections":[],"references":{"doc://com.example.RegistryAPI/documentation/RegistryAPI/__scope___name___version_/get":{"navigatorTitle":[{"text":"GET \/{scope}\/{name}\/{version}","kind":"text"}],"kind":"symbol","url":"\/documentation\/registryapi\/__scope___name___version_\/get","type":"topic","fragments":[{"text":"GET","kind":"text"}],"identifier":"doc:\/\/com.example.RegistryAPI\/documentation\/RegistryAPI\/__scope___name___version_\/get","abstract":[{"type":"strong","inlineContent":[{"text":"Responses:","type":"text"}]}],"title":"Fetch metadata for a package release","role":"symbol"},"doc://com.example.RegistryAPI/documentation/RegistryAPI/__scope___name___version_.zip/get/401":{"abstract":[{"text":"Referenced response","type":"text"}],"type":"topic","role":"symbol","kind":"symbol","title":"401 Response","navigatorTitle":[{"kind":"text","text":"401 Response"}],"identifier":"doc:\/\/com.example.RegistryAPI\/documentation\/RegistryAPI\/__scope___name___version_.zip\/get\/401","url":"\/documentation\/registryapi\/__scope___name___version_.zip\/get\/401"},"doc://com.example.RegistryAPI/documentation/RegistryAPI":{"title":"RegistryAPI","kind":"symbol","url":"\/documentation\/registryapi","abstract":[{"text":"Interact with Swift packages through a standardized API for publishing, discovering, and retrieving packages.","type":"text"}],"identifier":"doc:\/\/com.example.RegistryAPI\/documentation\/RegistryAPI","type":"topic","role":"collection"},"doc://com.example.RegistryAPI/documentation/RegistryAPI/__scope___name___version_":{"title":"\/{scope}\/{name}\/{version}","navigatorTitle":[{"kind":"text","text":"\/{scope}\/{name}\/{version}"}],"abstract":[],"type":"topic","identifier":"doc:\/\/com.example.RegistryAPI\/documentation\/RegistryAPI\/__scope___name___version_","url":"\/documentation\/registryapi\/__scope___name___version_","kind":"symbol","role":"symbol"}}} No newline at end of file | |||
There was a problem hiding this comment.
The 401 response documentation lacks a detailed description of the authentication failure scenario
| @@ -0,0 +1 @@ | |||
| Subproject commit 4d53b74c5cf5cdd45526a07d89c2e017b8989b9e | |||
There was a problem hiding this comment.
Git submodule reference added without corresponding .gitmodules configuration
There was a problem hiding this comment.
Pull Request Overview
This PR adds support for converting OpenAPI documents to DocC symbol graphs along with generating enhanced API documentation. Key changes include:
- Updates to the OpenAPIDocCConverter to use DocC.SymbolGraphGenerator with a fallback for the module name.
- Addition of a new Converter module that converts OpenAPI documents to SymbolGraph objects.
- Improvements to the CLI with a renamed command ("openapi-to-docc") and refined argument handling.
- Extensive additions and updates to documentation covering Security, Rate Limiting, Publishing, Authentication, and more.
Reviewed Changes
Copilot reviewed 129 out of 135 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| Sources/Integration/OpenAPIDocCConverter.swift | Updated to use DocC.SymbolGraphGenerator with dynamic module naming. |
| Sources/Integration/Converter.swift | New file to convert OpenAPI documents into SymbolGraph format. |
| Sources/CLI/main.swift | Refactored CLI command and argument options, with minor renaming. |
| RegistryAPI.docc/* (multiple) | Added and updated comprehensive API documentation examples. |
| Package.swift | Updated dependency URL for swift-docc-symbolkit. |
Files not reviewed (6)
- RegistryAPI.docc/Resources/css/custom.css: Language not supported
- docc-sample: Language not supported
- docs/.nojekyll: Language not supported
- docs/data/documentation/registry-api/authentication.json: Language not supported
- docs/data/documentation/registry-api/errorcodes.json: Language not supported
- docs/data/documentation/registry-api/gettingstarted.json: Language not supported
Comments suppressed due to low confidence (2)
Sources/CLI/main.swift:22
- [nitpick] The CLI now defines both an 'output' and an 'outputPath' option for the output directory, which could be confusing. Consider unifying these options or clarifying their distinct purposes in the help text.
@Option(name: .customLong("output-path"), help: "Alternative name for output directory")
Sources/CLI/main.swift:16
- [nitpick] The argument for the input file has been renamed from 'inputPath' to 'input', which may be less descriptive. Consider renaming it to 'inputPath' to maintain clarity with the file path information.
@Argument(help: "The path to the OpenAPI document (YAML or JSON)")
There was a problem hiding this comment.
Pull Request Overview
This PR adds support for the OpenAPI format and enhances the generated API documentation, both through new conversion paths and several documentation updates. Key changes include:
- Updating the OpenAPIDocCConverter to use DocC’s SymbolGraphGenerator with a fallback for module name.
- Adding a new Converter for OpenAPI to SymbolGraph conversion along with CLI improvements.
- Expanding documentation with new tutorials and resource files, and adjusting dependency URLs in Package.swift.
Reviewed Changes
Copilot reviewed 129 out of 135 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| Sources/Integration/OpenAPIDocCConverter.swift | Updated to select module name and use DocC.SymbolGraphGenerator |
| Sources/Integration/Converter.swift | New conversion implementation from OpenAPI to SymbolGraph |
| Sources/CLI/main.swift | Updated CLI command, options, and error handling for output parameters |
| RegistryAPI.docc/* | Added multiple new documentation tutorials and resource files for the API |
| Package.swift | Updated dependency URL for swift-docc-symbolkit |
Files not reviewed (6)
- RegistryAPI.docc/Resources/css/custom.css: Language not supported
- docc-sample: Language not supported
- docs/.nojekyll: Language not supported
- docs/data/documentation/registry-api/authentication.json: Language not supported
- docs/data/documentation/registry-api/errorcodes.json: Language not supported
- docs/data/documentation/registry-api/gettingstarted.json: Language not supported
Comments suppressed due to low confidence (2)
Sources/CLI/main.swift:22
- [nitpick] Having both 'output' and 'outputPath' options may cause confusion. Consider unifying these options under a single, clear parameter name for consistency.
@Option(name: .customLong("output-path"), help: "Alternative name for output directory")
Package.swift:27
- [nitpick] Verify that the dependency URL update for swift-docc-symbolkit is intentional and that the new repository meets your project's requirements, as this change could affect dependency resolution.
.package(url: "https://github.com/swiftlang/swift-docc-symbolkit.git", from: "1.0.0"),
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Documentation.
Summary by mrge
Added support for OpenAPI format and generated full API documentation for the Swift Package Registry.