pkg-proxy/docs/swagger/swagger.json
Andrew Nesbitt beddf8357a
Fix startup message and add connectivity check for S3 storage (#57)
* Fix startup message and add connectivity check for S3 storage

When S3 storage is configured, the startup log incorrectly showed the
default local path (./cache/artifacts) instead of the actual S3 URL.
This also adds a lightweight connectivity check at startup so bad
credentials or endpoints fail immediately rather than on first request.

Add URL() and Close() to the Storage interface so all backends report
their URL and can be cleaned up properly. Rename the stats JSON field
from storage_path to storage_url. Close storage in error paths and
during graceful shutdown.

Fixes #49

* Fix Windows test assertion for file:// URL format

OpenBucket normalizes Windows paths to file:///C:/path (three slashes)
but the test expected file://C:/path (two slashes).
2026-04-03 14:06:51 +01:00

1025 lines
No EOL
32 KiB
JSON

{
"swagger": "2.0",
"info": {
"description": "HTTP API for package enrichment, vulnerability lookup, cache stats, and source browsing.",
"title": "git-pkgs proxy API",
"contact": {},
"version": "0.1.0"
},
"basePath": "/",
"paths": {
"/api/browse/{ecosystem}/{name}/{version}": {
"get": {
"description": "Lists files from the first cached artifact for a package version.",
"produces": [
"application/json"
],
"tags": [
"browse"
],
"summary": "List files inside a cached artifact",
"parameters": [
{
"type": "string",
"description": "Ecosystem",
"name": "ecosystem",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Package name",
"name": "name",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Version",
"name": "version",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Directory path inside the archive",
"name": "path",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/server.BrowseListResponse"
}
},
"404": {
"description": "Not Found",
"schema": {
"type": "string"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "string"
}
}
}
}
},
"/api/browse/{ecosystem}/{name}/{version}/file/{filepath}": {
"get": {
"description": "Streams a single file from the cached artifact. The file path may contain slashes.",
"produces": [
"application/octet-stream"
],
"tags": [
"browse"
],
"summary": "Fetch a file inside a cached artifact",
"parameters": [
{
"type": "string",
"description": "Ecosystem",
"name": "ecosystem",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Package name",
"name": "name",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Version",
"name": "version",
"in": "path",
"required": true
},
{
"type": "string",
"description": "File path inside the archive",
"name": "filepath",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "file"
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "string"
}
},
"404": {
"description": "Not Found",
"schema": {
"type": "string"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "string"
}
}
}
}
},
"/api/bulk": {
"post": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"api"
],
"summary": "Bulk package lookup by PURL",
"parameters": [
{
"description": "PURLs",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/server.BulkRequest"
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/server.BulkResponse"
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "string"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "string"
}
}
}
}
},
"/api/compare/{ecosystem}/{name}/{fromVersion}/{toVersion}": {
"get": {
"description": "Returns a structured diff for two cached versions.",
"produces": [
"application/json"
],
"tags": [
"browse"
],
"summary": "Compare two cached versions",
"parameters": [
{
"type": "string",
"description": "Ecosystem",
"name": "ecosystem",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Package name",
"name": "name",
"in": "path",
"required": true
},
{
"type": "string",
"description": "From version",
"name": "fromVersion",
"in": "path",
"required": true
},
{
"type": "string",
"description": "To version",
"name": "toVersion",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"additionalProperties": true
}
},
"404": {
"description": "Not Found",
"schema": {
"type": "string"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "string"
}
}
}
}
},
"/api/outdated": {
"post": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"api"
],
"summary": "Check outdated packages",
"parameters": [
{
"description": "Packages to check",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/server.OutdatedRequest"
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/server.OutdatedResponse"
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "string"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "string"
}
}
}
}
},
"/api/package/{ecosystem}/{name}": {
"get": {
"description": "Returns enriched package metadata. URL-encode scoped names (e.g. @scope/name -\u003e %40scope%2Fname).",
"produces": [
"application/json"
],
"tags": [
"api"
],
"summary": "Get package metadata",
"parameters": [
{
"type": "string",
"description": "Ecosystem",
"name": "ecosystem",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Package name",
"name": "name",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/server.PackageResponse"
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "string"
}
},
"404": {
"description": "Not Found",
"schema": {
"type": "string"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "string"
}
}
}
}
},
"/api/package/{ecosystem}/{name}/{version}": {
"get": {
"description": "Returns enriched package+version metadata and vulnerability data.",
"produces": [
"application/json"
],
"tags": [
"api"
],
"summary": "Get version metadata and vulnerabilities",
"parameters": [
{
"type": "string",
"description": "Ecosystem",
"name": "ecosystem",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Package name",
"name": "name",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Version",
"name": "version",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/server.EnrichmentResponse"
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "string"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "string"
}
}
}
}
},
"/api/packages": {
"get": {
"produces": [
"application/json"
],
"tags": [
"api"
],
"summary": "List cached packages",
"parameters": [
{
"type": "string",
"description": "Ecosystem",
"name": "ecosystem",
"in": "query"
},
{
"enum": [
"hits",
"name",
"size",
"cached_at",
"ecosystem",
"vulns"
],
"type": "string",
"description": "Sort",
"name": "sort",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/server.PackagesListResponse"
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "string"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "string"
}
}
}
}
},
"/api/search": {
"get": {
"produces": [
"application/json"
],
"tags": [
"api"
],
"summary": "Search cached packages",
"parameters": [
{
"type": "string",
"description": "Query",
"name": "q",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Ecosystem",
"name": "ecosystem",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/server.SearchResponse"
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "string"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "string"
}
}
}
}
},
"/api/vulns/{ecosystem}/{name}": {
"get": {
"description": "Returns vulnerabilities for a package across versions, or for a specific version if provided.",
"produces": [
"application/json"
],
"tags": [
"api"
],
"summary": "Get vulnerabilities for a package or version",
"parameters": [
{
"type": "string",
"description": "Ecosystem",
"name": "ecosystem",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Package name",
"name": "name",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/server.VulnsResponse"
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "string"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "string"
}
}
}
}
},
"/api/vulns/{ecosystem}/{name}/{version}": {
"get": {
"description": "Returns vulnerabilities for a package across versions, or for a specific version if provided.",
"produces": [
"application/json"
],
"tags": [
"api"
],
"summary": "Get vulnerabilities for a package or version",
"parameters": [
{
"type": "string",
"description": "Ecosystem",
"name": "ecosystem",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Package name",
"name": "name",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Version",
"name": "version",
"in": "path"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/server.VulnsResponse"
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "string"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "string"
}
}
}
}
},
"/health": {
"get": {
"produces": [
"text/plain"
],
"tags": [
"meta"
],
"summary": "Health check",
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "string"
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"type": "string"
}
}
}
}
},
"/stats": {
"get": {
"produces": [
"application/json"
],
"tags": [
"meta"
],
"summary": "Cache statistics",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/server.StatsResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "string"
}
}
}
}
}
},
"definitions": {
"server.BrowseFileInfo": {
"type": "object",
"properties": {
"is_dir": {
"type": "boolean"
},
"mod_time": {
"type": "string"
},
"name": {
"type": "string"
},
"path": {
"type": "string"
},
"size": {
"type": "integer"
}
}
},
"server.BrowseListResponse": {
"type": "object",
"properties": {
"files": {
"type": "array",
"items": {
"$ref": "#/definitions/server.BrowseFileInfo"
}
},
"path": {
"type": "string"
}
}
},
"server.BulkRequest": {
"type": "object",
"properties": {
"purls": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"server.BulkResponse": {
"type": "object",
"properties": {
"packages": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/server.PackageResponse"
}
}
}
},
"server.EnrichmentResponse": {
"type": "object",
"properties": {
"is_outdated": {
"type": "boolean"
},
"license_category": {
"type": "string"
},
"package": {
"$ref": "#/definitions/server.PackageResponse"
},
"version": {
"$ref": "#/definitions/server.VersionResponse"
},
"vulnerabilities": {
"type": "array",
"items": {
"$ref": "#/definitions/server.VulnResponse"
}
}
}
},
"server.OutdatedPackage": {
"type": "object",
"properties": {
"ecosystem": {
"type": "string"
},
"name": {
"type": "string"
},
"version": {
"type": "string"
}
}
},
"server.OutdatedRequest": {
"type": "object",
"properties": {
"packages": {
"type": "array",
"items": {
"$ref": "#/definitions/server.OutdatedPackage"
}
}
}
},
"server.OutdatedResponse": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/definitions/server.OutdatedResult"
}
}
}
},
"server.OutdatedResult": {
"type": "object",
"properties": {
"ecosystem": {
"type": "string"
},
"is_outdated": {
"type": "boolean"
},
"latest_version": {
"type": "string"
},
"name": {
"type": "string"
},
"version": {
"type": "string"
}
}
},
"server.PackageListResult": {
"type": "object",
"properties": {
"cached_at": {
"type": "string"
},
"ecosystem": {
"type": "string"
},
"hits": {
"type": "integer"
},
"latest_version": {
"type": "string"
},
"license": {
"type": "string"
},
"license_category": {
"type": "string"
},
"name": {
"type": "string"
},
"size": {
"type": "integer"
},
"vuln_count": {
"type": "integer"
}
}
},
"server.PackageResponse": {
"type": "object",
"properties": {
"description": {
"type": "string"
},
"ecosystem": {
"type": "string"
},
"homepage": {
"type": "string"
},
"latest_version": {
"type": "string"
},
"license": {
"type": "string"
},
"license_category": {
"type": "string"
},
"name": {
"type": "string"
},
"registry_url": {
"type": "string"
},
"repository": {
"type": "string"
}
}
},
"server.PackagesListResponse": {
"type": "object",
"properties": {
"count": {
"type": "integer"
},
"ecosystem": {
"type": "string"
},
"page": {
"type": "integer"
},
"per_page": {
"type": "integer"
},
"results": {
"type": "array",
"items": {
"$ref": "#/definitions/server.PackageListResult"
}
},
"sort_by": {
"type": "string"
},
"total": {
"type": "integer"
}
}
},
"server.SearchPackageResult": {
"type": "object",
"properties": {
"cached_at": {
"type": "string"
},
"ecosystem": {
"type": "string"
},
"hits": {
"type": "integer"
},
"latest_version": {
"type": "string"
},
"license": {
"type": "string"
},
"name": {
"type": "string"
},
"size": {
"type": "integer"
}
}
},
"server.SearchResponse": {
"type": "object",
"properties": {
"count": {
"type": "integer"
},
"query": {
"type": "string"
},
"results": {
"type": "array",
"items": {
"$ref": "#/definitions/server.SearchPackageResult"
}
}
}
},
"server.StatsResponse": {
"type": "object",
"properties": {
"cached_artifacts": {
"type": "integer"
},
"database_path": {
"type": "string"
},
"storage_url": {
"type": "string"
},
"total_size": {
"type": "string"
},
"total_size_bytes": {
"type": "integer"
}
}
},
"server.VersionResponse": {
"type": "object",
"properties": {
"ecosystem": {
"type": "string"
},
"integrity": {
"type": "string"
},
"is_outdated": {
"type": "boolean"
},
"license": {
"type": "string"
},
"name": {
"type": "string"
},
"published_at": {
"type": "string"
},
"version": {
"type": "string"
},
"yanked": {
"type": "boolean"
}
}
},
"server.VulnResponse": {
"type": "object",
"properties": {
"cvss_score": {
"type": "number"
},
"fixed_version": {
"type": "string"
},
"id": {
"type": "string"
},
"references": {
"type": "array",
"items": {
"type": "string"
}
},
"severity": {
"type": "string"
},
"summary": {
"type": "string"
}
}
},
"server.VulnsResponse": {
"type": "object",
"properties": {
"count": {
"type": "integer"
},
"ecosystem": {
"type": "string"
},
"name": {
"type": "string"
},
"version": {
"type": "string"
},
"vulnerabilities": {
"type": "array",
"items": {
"$ref": "#/definitions/server.VulnResponse"
}
}
}
}
}
}