Skip to content

Commit 4f81605

Browse files
jmgilmanjmgilman
authored
docs(api): adds swagger (#183)
1 parent fcc9b29 commit 4f81605

File tree

16 files changed

+5156
-6
lines changed

16 files changed

+5156
-6
lines changed

‎foundry/api/.env.example

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# Server configuration
2-
export HTTP_PORT=8080
2+
export HTTP_PORT=5050
33
export SERVER_TIMEOUT=30s
44

55
# Database configuration

‎foundry/api/.justfile

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
up:
2+
docker compose up -d auth auth-jwt api postgres
3+
4+
down:
5+
rm -rf .secret && docker compose down
6+
7+
docker:
8+
earthly --config "" +docker
9+
10+
login:
11+
(cd ../../cli && go run cmd/main.go -vvv --api-url "http://localhost:5050" api login "$(cat ../foundry/api/.secret/jwt.txt)")
12+
13+
swagger:
14+
earthly --config "" +swagger

‎foundry/api/Earthfile

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ src:
2323

2424
CACHE --persist --sharing shared /go
2525

26-
COPY --dir client cmd internal pkg .
26+
COPY --dir client cmd docs internal pkg .
2727
RUN go generate ./...
2828

2929
SAVE ARTIFACT . src
@@ -112,4 +112,18 @@ jwt:
112112
RUN mkdir -p /jwt
113113
RUN ./bin/foundry-api auth generate -a -k ./certs/private.pem > /jwt/token.txt
114114

115-
SAVE ARTIFACT /jwt jwt
115+
SAVE ARTIFACT /jwt jwt
116+
117+
swagger:
118+
FROM +src
119+
120+
RUN go install github.com/swaggo/swag/cmd/swag@latest
121+
RUN swag init -g cmd/api/main.go -o docs
122+
123+
SAVE ARTIFACT docs docs AS LOCAL docs
124+
125+
check-swagger:
126+
FROM +swagger
127+
128+
COPY --dir docs /docs
129+
RUN diff -r docs ../docs

‎foundry/api/README.md

Lines changed: 128 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,130 @@
1-
# Foundry
1+
# Catalyst Foundry API
22

3-
Foundry provides the middleware for routing deployments from forge to a GitOps repository.
3+
This is the API server for the Catalyst Foundry system, providing endpoints for managing releases and deployments.
44

5-
Note that this service is currently incomplete and is a work in progress.
5+
## API Documentation
6+
7+
The API documentation is generated using Swagger/OpenAPI and is available in two formats:
8+
9+
1. **Interactive Swagger UI**: Available at `/swagger/index.html` when the server is running
10+
2. **OpenAPI JSON**: Available at `/swagger/doc.json` when the server is running
11+
12+
## Getting Started
13+
14+
### Prerequisites
15+
16+
- Go 1.24.2 or later
17+
- PostgreSQL database
18+
- Kubernetes cluster (optional, for deployment features)
19+
20+
### Installation
21+
22+
1. Install dependencies:
23+
```bash
24+
make deps
25+
```
26+
27+
2. Install Swagger tools (one-time setup):
28+
```bash
29+
make swagger-init
30+
```
31+
32+
3. Generate API documentation:
33+
```bash
34+
make swagger-gen
35+
```
36+
37+
4. Build and run the API:
38+
```bash
39+
make run
40+
```
41+
42+
### Development
43+
44+
For development with auto-generated documentation:
45+
46+
```bash
47+
make dev
48+
```
49+
50+
This will generate the documentation and start the server.
51+
52+
## API Endpoints
53+
54+
### Health Check
55+
- `GET /healthz` - Check API health status
56+
57+
### GitHub Actions Authentication
58+
- `POST /gha/validate` - Validate GitHub Actions OIDC token
59+
- `POST /gha/auth` - Create GHA authentication configuration
60+
- `GET /gha/auth` - List GHA authentication configurations
61+
- `GET /gha/auth/:id` - Get specific GHA authentication configuration
62+
- `GET /gha/auth/repository/:repository` - Get GHA auth by repository
63+
- `PUT /gha/auth/:id` - Update GHA authentication configuration
64+
- `DELETE /gha/auth/:id` - Delete GHA authentication configuration
65+
66+
### Releases
67+
- `POST /release` - Create a new release
68+
- `GET /release/:id` - Get a specific release
69+
- `PUT /release/:id` - Update a release
70+
- `GET /releases` - List all releases
71+
72+
### Release Aliases
73+
- `GET /release/alias/:name` - Get release by alias
74+
- `POST /release/alias/:name` - Create an alias for a release
75+
- `DELETE /release/alias/:name` - Delete an alias
76+
- `GET /release/:id/aliases` - List aliases for a release
77+
78+
### Deployments
79+
- `POST /release/:id/deploy` - Create a deployment for a release
80+
- `GET /release/:id/deploy/:deployId` - Get a specific deployment
81+
- `PUT /release/:id/deploy/:deployId` - Update a deployment
82+
- `GET /release/:id/deployments` - List deployments for a release
83+
- `GET /release/:id/deploy/latest` - Get the latest deployment
84+
85+
### Deployment Events
86+
- `POST /release/:id/deploy/:deployId/events` - Add an event to a deployment
87+
- `GET /release/:id/deploy/:deployId/events` - Get events for a deployment
88+
89+
## Authentication
90+
91+
The API uses JWT tokens for authentication. Most endpoints require authentication with the following permissions:
92+
93+
- `PermReleaseRead` - Read access to releases
94+
- `PermReleaseWrite` - Write access to releases
95+
- `PermDeploymentRead` - Read access to deployments
96+
- `PermDeploymentWrite` - Write access to deployments
97+
- `PermDeploymentEventRead` - Read access to deployment events
98+
- `PermDeploymentEventWrite` - Write access to deployment events
99+
- `PermGHAAuthRead` - Read access to GHA authentication
100+
- `PermGHAAuthWrite` - Write access to GHA authentication
101+
102+
## Configuration
103+
104+
The API can be configured using environment variables or command-line flags. See the main application help for details:
105+
106+
```bash
107+
./bin/foundry-api --help
108+
```
109+
110+
## Documentation Generation
111+
112+
To regenerate the API documentation after making changes:
113+
114+
```bash
115+
make swagger-gen
116+
```
117+
118+
This will update the `docs/` directory with the latest API documentation.
119+
120+
## Testing
121+
122+
Run the tests:
123+
124+
```bash
125+
go test ./...
126+
```
127+
128+
## License
129+
130+
This project is licensed under the Apache License 2.0.

‎foundry/api/cmd/api/main.go

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,10 +25,32 @@ import (
2525
"github.com/input-output-hk/catalyst-forge/foundry/api/pkg/k8s/mocks"
2626
"gorm.io/driver/postgres"
2727
"gorm.io/gorm"
28+
29+
_ "github.com/input-output-hk/catalyst-forge/foundry/api/docs"
2830
)
2931

3032
var version = "dev"
3133

34+
// @title Catalyst Foundry API
35+
// @version 1.0
36+
// @description API for managing releases and deployments in the Catalyst Foundry system.
37+
// @termsOfService http://swagger.io/terms/
38+
39+
// @contact.name API Support
40+
// @contact.url http://www.swagger.io/support
41+
// @contact.email [email protected]
42+
43+
// @license.name Apache 2.0
44+
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
45+
46+
// @host localhost:5050
47+
// @BasePath /
48+
49+
// @securityDefinitions.apikey BearerAuth
50+
// @in header
51+
// @name Authorization
52+
// @description Type "Bearer" followed by a space and JWT token.
53+
3254
var mockK8sClient = mocks.ClientMock{
3355
CreateDeploymentFunc: func(ctx context.Context, deployment *models.ReleaseDeployment) error {
3456
return nil

‎foundry/api/docker-compose.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ services:
4040
LOG_FORMAT: text
4141
ports:
4242
- "5050:5050"
43+
- "8080:8080"
4344
volumes:
4445
- ./.secret:/data
4546
healthcheck:

0 commit comments

Comments
 (0)