Skip to content

Commit 488d27d

Browse files
ayushshrivastvayushshrivastv
committed
Add OpenAPI format support and generated documentation
1 parent 8849b85 commit 488d27d

File tree

132 files changed

+5240
-112
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

132 files changed

+5240
-112
lines changed

‎Package.resolved

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
{
2222
"identity" : "swift-docc-symbolkit",
2323
"kind" : "remoteSourceControl",
24-
"location" : "https://github.com/apple/swift-docc-symbolkit.git",
24+
"location" : "https://github.com/swiftlang/swift-docc-symbolkit.git",
2525
"state" : {
2626
"revision" : "b45d1f2ed151d057b54504d653e0da5552844e34",
2727
"version" : "1.0.0"

‎Package.swift

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ let package = Package(
2424
dependencies: [
2525
.package(url: "https://github.com/jpsim/Yams.git", from: "5.0.6"),
2626
.package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.2.0"),
27-
.package(url: "https://github.com/apple/swift-docc-symbolkit.git", from: "1.0.0"),
27+
.package(url: "https://github.com/swiftlang/swift-docc-symbolkit.git", from: "1.0.0"),
2828
.package(url: "https://github.com/mattpolzin/OpenAPIKit.git", from: "3.0.0"),
2929
],
3030
targets: [
@@ -52,8 +52,8 @@ let package = Package(
5252
.target(
5353
name: "Integration",
5454
dependencies: [
55-
"OpenAPI",
56-
"DocC",
55+
"OpenAPI",
56+
"DocC",
5757
"Core",
5858
.product(name: "SymbolKit", package: "swift-docc-symbolkit")
5959
],
@@ -63,8 +63,8 @@ let package = Package(
6363
.target(
6464
name: "OpenAPItoSymbolGraph",
6565
dependencies: [
66-
"OpenAPI",
67-
"DocC",
66+
"OpenAPI",
67+
"DocC",
6868
"Integration",
6969
"Core",
7070
.product(name: "SymbolKit", package: "swift-docc-symbolkit")
@@ -98,9 +98,9 @@ let package = Package(
9898
.testTarget(
9999
name: "OpenAPItoSymbolGraphTests",
100100
dependencies: [
101-
"OpenAPI",
102-
"DocC",
103-
"Integration",
101+
"OpenAPI",
102+
"DocC",
103+
"Integration",
104104
"OpenAPItoSymbolGraph",
105105
"Core",
106106
"CLI",

‎RegistryAPI.docc/Extensions/PackageMetadata.md

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# ``RegistryAPI/PackageMetadata``
2+
3+
A comprehensive representation of metadata for a Swift package.
4+
5+
## Overview
6+
7+
The `PackageMetadata` structure contains all descriptive information about a Swift package, including details about the package's author, license, and available versions.
8+
9+
```swift
10+
// Example: Fetching and using package metadata
11+
let url = URL(string: "https://registry.example.com/mona/LinkedList")!
12+
let (data, _) = try await URLSession.shared.data(from: url)
13+
let metadata = try JSONDecoder().decode(PackageMetadata.self, from: data)
14+
15+
// Use metadata properties
16+
print("Package name: \(metadata.name)")
17+
print("Latest version: \(metadata.latestVersion)")
18+
print("Available versions: \(metadata.versions.joined(separator: ", "))")
19+
```
20+
21+
Package metadata provides a complete picture of a package, including:
22+
23+
- Basic information like name, version, and description
24+
- Author and organization information
25+
- License details
26+
- Repository location
27+
- Available versions
28+
29+
## Topics
30+
31+
### Essential Properties
32+
33+
- ``name``
34+
- ``description``
35+
- ``version``
36+
- ``latestVersion``
37+
38+
### Author Information
39+
40+
- ``author``
41+
- ``PackageAuthor``
42+
- ``organization``
43+
- ``PackageOrganization``
44+
45+
### Package Versions
46+
47+
- ``versions``
48+
- ``listedVersions``
49+
- ``ListedRelease``
50+
51+
### Package Resources
52+
53+
- ``repository``
54+
- ``license``
55+
- ``readmeURL``
56+
- ``keywords``
57+
58+
## Structure
59+
60+
```json
61+
{
62+
"name": "LinkedList",
63+
"description": "A linked list implementation for Swift",
64+
"keywords": ["data-structure", "list", "collection"],
65+
"version": "1.1.1",
66+
"author": {
67+
"name": "J. Appleseed",
68+
"email": "japplseed@example.com",
69+
"url": "https://example.com/japplseed"
70+
},
71+
"organization": {
72+
"name": "Example Organization",
73+
"url": "https://example.com",
74+
"description": "Organization that maintains the package"
75+
},
76+
"license": {
77+
"name": "MIT",
78+
"url": "https://opensource.org/licenses/MIT"
79+
},
80+
"repository": {
81+
"type": "git",
82+
"url": "https://github.com/mona/LinkedList.git"
83+
},
84+
"readmeURL": "https://registry.example.com/mona/LinkedList/1.1.1/README.md",
85+
"latestVersion": "1.1.1",
86+
"versions": ["1.0.0", "1.0.1", "1.1.0", "1.1.1"]
87+
}
88+
```
89+
90+
## Accessing Metadata
91+
92+
You can retrieve package metadata using the package identifier endpoint:
93+
94+
```swift
95+
func fetchPackageMetadata(scope: String, name: String) async throws -> PackageMetadata {
96+
let url = URL(string: "https://registry.example.com/\(scope)/\(name)")!
97+
98+
var request = URLRequest(url: url)
99+
request.addValue("application/json", forHTTPHeaderField: "Accept")
100+
101+
let (data, response) = try await URLSession.shared.data(for: request)
102+
103+
guard let httpResponse = response as? HTTPURLResponse,
104+
(200..<300).contains(httpResponse.statusCode) else {
105+
throw FetchError.invalidResponse
106+
}
107+
108+
return try JSONDecoder().decode(PackageMetadata.self, from: data)
109+
}
110+
```
111+
112+
## Required and Optional Fields
113+
114+
The following fields are required in every package metadata response:
115+
116+
- `name`: Package name
117+
- `version`: Current version
118+
- `description`: Brief description of the package
119+
- `license`: License information
120+
121+
All other fields are optional and may not be present in all responses.
122+
123+
## Handling Missing Fields
124+
125+
When working with package metadata, it's important to handle optional fields gracefully:
126+
127+
```swift
128+
// Example: Handling optional fields
129+
func displayPackageInfo(_ metadata: PackageMetadata) {
130+
// Required fields
131+
print("Package: \(metadata.name)")
132+
print("Description: \(metadata.description)")
133+
134+
// Optional fields
135+
if let author = metadata.author {
136+
print("Author: \(author.name)")
137+
if let email = author.email {
138+
print("Contact: \(email)")
139+
}
140+
}
141+
142+
if let org = metadata.organization {
143+
print("Organization: \(org.name)")
144+
}
145+
146+
// Keywords
147+
if let keywords = metadata.keywords, !keywords.isEmpty {
148+
print("Keywords: \(keywords.joined(separator: ", "))")
149+
}
150+
}
151+
```
152+
153+
## See Also
154+
155+
- ``RegistryAPI/__scope___name_``
156+
- ``RegistryAPI/ReleaseResource``
157+
- ``RegistryAPI/ListedRelease``

‎RegistryAPI.docc/RegistryAPI.md

Lines changed: 67 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,71 @@
1-
# RegistryAPI
1+
# ``RegistryAPI``
22

3-
Swift Package Registry API documentation.
3+
Interact with Swift packages through a standardized API for publishing, discovering, and retrieving packages.
44

55
## Overview
66

7-
This documentation provides details about the Swift Package Registry API endpoints and schemas, generated from the OpenAPI specification.
7+
The Swift Package Registry API provides a robust interface for package management that follows open standards. Using this API, you can:
8+
9+
- **Discover** packages through search and metadata
10+
- **Retrieve** package releases including source code and manifests
11+
- **Publish** your own packages for others to use
12+
- **Authenticate** to access private packages or perform privileged operations
13+
14+
![A diagram showing the workflow of package discovery, retrieval and publishing](registry_workflow.png)
15+
16+
The API follows RESTful principles with well-defined endpoints for each resource type. All requests and responses use standard HTTP methods and status codes, with JSON-formatted data.
17+
18+
```swift
19+
// Example: Retrieve package metadata
20+
let url = URL(string: "https://registry.example.com/mona/LinkedList")!
21+
let (data, response) = try await URLSession.shared.data(from: url)
22+
let metadata = try JSONDecoder().decode(PackageMetadata.self, from: data)
23+
24+
print("Package: \(metadata.name)")
25+
print("Latest version: \(metadata.latestVersion)")
26+
print("Available versions: \(metadata.versions.joined(separator: ", "))")
27+
```
28+
29+
## Topics
30+
31+
### Getting Started
32+
33+
- <doc:GettingStarted>
34+
- <doc:Authentication>
35+
- <doc:Publishing>
36+
37+
### Core Concepts
38+
39+
- ``RegistryAPI/PackageMetadata``
40+
- ``RegistryAPI/ReleaseResource``
41+
- ``RegistryAPI/Identifier``
42+
43+
### Package Discovery
44+
45+
- ``RegistryAPI/_identifiers``
46+
- ``RegistryAPI/__scope___name_``
47+
48+
### Package Retrieval
49+
50+
- ``RegistryAPI/__scope___name___version_``
51+
- ``RegistryAPI/__scope___name___version_.zip``
52+
- ``RegistryAPI/__scope___name___version__package.swift``
53+
54+
### Package Publishing
55+
56+
- ``RegistryAPI/__scope___name___version_/put``
57+
58+
### Authentication
59+
60+
- ``RegistryAPI/_login``
61+
62+
### Error Handling
63+
64+
- ``RegistryAPI/ProblemDetails``
65+
- <doc:ErrorCodes>
66+
67+
### Best Practices
68+
69+
- <doc:RateLimiting>
70+
- <doc:Security>
71+
- <doc:Performance>

‎RegistryAPI.docc/Resources/VersionEndpoint.md

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# ``RegistryAPI/__scope___name___version_``
2+
3+
Interact with a specific version of a Swift package.
4+
5+
## Overview
6+
7+
This endpoint provides access to a specific version of a package in the registry. It supports both retrieving metadata about a version and publishing new versions.
8+
9+
## Getting Version Information
10+
11+
Retrieve information about a specific version of a package:
12+
13+
```http
14+
GET /{scope}/{name}/{version}
15+
```
16+
17+
### Response
18+
19+
On success, returns a `200 OK` response with a `ReleaseResource` object in the response body:
20+
21+
```json
22+
{
23+
"id": "mona/LinkedList/1.1.1",
24+
"version": "1.1.1",
25+
"resources": [
26+
{
27+
"name": "source-archive",
28+
"type": "application/zip",
29+
"checksum": "a2ac54cf25fbc1ad0028f03f0aa4b96833b83bb05a14e510892bb27dea4dc812",
30+
"signing": {
31+
"signatureBase64Encoded": "ZXhhbXBsZSBzaWduYXR1cmU=",
32+
"signatureFormat": "cms-1.0.0"
33+
}
34+
}
35+
],
36+
"metadata": {
37+
"author": {
38+
"name": "J. Appleseed"
39+
},
40+
"description": "A linked list implementation for Swift",
41+
"licenseURL": "https://opensource.org/licenses/MIT"
42+
}
43+
}
44+
```
45+
46+
## Publishing a New Version
47+
48+
To publish a new version of a package:
49+
50+
```http
51+
PUT /{scope}/{name}/{version}
52+
Content-Type: application/octet-stream
53+
X-Swift-Package-Signature: sha256=[Base64 encoded signature]
54+
```
55+
56+
The request body should contain the package archive in ZIP format.
57+
58+
### Response Codes
59+
60+
When publishing a package version, the registry may respond with:
61+
62+
| Status Code | Description |
63+
|-------------|-------------|
64+
| 201 Created | Version published successfully |
65+
| 202 Accepted | Version accepted for processing |
66+
| 400 Bad Request | Invalid request format |
67+
| 401 Unauthorized | Authentication required |
68+
| 403 Forbidden | Insufficient permissions |
69+
| 409 Conflict | Version already exists |
70+
| 413 Payload Too Large | Package size exceeds limits |
71+
| 422 Unprocessable Entity | Package validation failed |
72+
73+
## Availability
74+
75+
The endpoint is available for both public and private packages. Private packages require authentication.
76+
77+
## See Also
78+
79+
- ``RegistryAPI/__scope___name_``
80+
- ``RegistryAPI/__scope___name___version_.zip``
81+
- ``RegistryAPI/ReleaseResource``

0 commit comments

Comments
 (0)