chore(docs): Generate basic OpenAPI specification

.github/workflows/lint.yml

@@ -49,11 +49,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
-      - uses: bufbuild/buf-setup-action@eb60cd0de4f14f1f57cf346916b8cd69a9e7ed0b # v1.26.1
+      - uses: bufbuild/buf-action@5150a1eef5c10b6a5cf8a69fc872f24a09473195 # v1.1.1
         with:
-          buf_user: ${{ secrets.buf_user }}
-          buf_api_token: ${{ secrets.buf_api_token }}
-      - uses: bufbuild/buf-lint-action@bd48f53224baaaf0fc55de9a913e7680ca6dbea4 # v1.0.3
+          version: 1.49.0
+          token: ${{ secrets.buf_api_token }}
+          breaking: false
+          pr_comment: false
 
   lint-dagger-module:
     runs-on: ubuntu-latest

Makefile

@@ -7,8 +7,8 @@ API_PROTO_FILES=$(shell find api -name *.proto)
 # generate api proto
 api:
 	cd ./pkg/attestation/crafter/api && buf generate
-	make -C ./app/controlplane api
-	make -C ./app/artifact-cas api
+	cd ./app/controlplane && make api
+	cd ./app/artifact-cas && make api
 
 .PHONY: config
 # generate config proto

app/artifact-cas/api/buf.lock

@@ -5,7 +5,14 @@ deps:
     owner: bufbuild
     repository: protovalidate
     commit: b983156c5e994cc9892e0ce3e64e17e0
+    digest: shake256:fb47a62989d38c2529bcc5cd86ded43d800eb84cee82b42b9e8a9e815d4ee8134a0fb9d0ce8299b27c2d2bbb7d6ade0c4ad5a8a4d467e1e2c7ca619ae9f634e2
   - remote: buf.build
     owner: googleapis
     repository: googleapis
-    commit: 7a6bc1e3207144b38e9066861e1de0ff
+    commit: 4ed3bc159a8b4ac68fe253218760d035
+    digest: shake256:7149cf5e9955c692d381e557830555d4e93f205a0f1b8e2dfdae46d029369aa3fc1980e35df0d310f7cc3b622f93e19ad276769a283a967dd3065ddfd3a40e13
+  - remote: buf.build
+    owner: grpc-ecosystem
+    repository: grpc-gateway
+    commit: 4c5ba75caaf84e928b7137ae5c18c26a
+    digest: shake256:e174ad9408f3e608f6157907153ffec8d310783ee354f821f57178ffbeeb8faa6bb70b41b61099c1783c82fe16210ebd1279bc9c9ee6da5cffba9f0e675b8b99

app/artifact-cas/api/buf.yaml

@@ -3,8 +3,8 @@ breaking:
   use:
     - FILE
 deps:
-  - buf.build/googleapis/googleapis
-  - buf.build/bufbuild/protovalidate
+  - buf.build/googleapis/googleapis:4ed3bc159a8b4ac68fe253218760d035
+  - buf.build/bufbuild/protovalidate:b983156c5e994cc9892e0ce3e64e17e0
 lint:
   use:
     - DEFAULT

app/artifact-cas/internal/conf/buf.lock

@@ -5,6 +5,7 @@ deps:
     owner: bufbuild
     repository: protovalidate
     commit: b983156c5e994cc9892e0ce3e64e17e0
+    digest: shake256:fb47a62989d38c2529bcc5cd86ded43d800eb84cee82b42b9e8a9e815d4ee8134a0fb9d0ce8299b27c2d2bbb7d6ade0c4ad5a8a4d467e1e2c7ca619ae9f634e2
   - remote: buf.build
     owner: googleapis
     repository: googleapis

app/artifact-cas/internal/conf/buf.yaml

@@ -3,8 +3,8 @@ breaking:
   use:
     - FILE
 deps:
-  - buf.build/googleapis/googleapis
-  - buf.build/bufbuild/protovalidate
+  - buf.build/googleapis/googleapis:4ed3bc159a8b4ac68fe253218760d035
+  - buf.build/bufbuild/protovalidate:b983156c5e994cc9892e0ce3e64e17e0
 lint:
   use:
     - DEFAULT

app/controlplane/Makefile

@@ -9,7 +9,11 @@ config: check-buf-tool
 # generate api proto bindings
 api: check-buf-tool
 	cd ./plugins/sdk/v1/plugin/api && buf generate
-	cd ./api && buf generate
+	cd ./api && buf generate && \
+	buf generate \
+		--path ./controlplane/v1/referrer.proto \
+		--path ./controlplane/v1/openapi_metadata.proto && \
+		../scripts/modify-openapi-schema.sh ${PWD}/api/gen temp-openapi/apidocs.swagger.json openapi/openapi/openapi.yaml openapi/openapi-extra.yaml
 
 .PHONY: build
 # build

app/controlplane/api/buf.gen.yaml

@@ -21,3 +21,8 @@ plugins:
       - useOptionals=messages # use optional TypeScript properties instead of undefined
   - plugin: buf.build/bufbuild/protoschema-jsonschema:v0.2.0
     out: ./gen/jsonschema
+  - plugin: buf.build/grpc-ecosystem/openapiv2:v2.26.3
+    out: gen/temp-openapi
+    opt:
+      - allow_merge=true
+      - json_names_for_fields=false

app/controlplane/api/buf.lock

@@ -5,11 +5,19 @@ deps:
     owner: bufbuild
     repository: protovalidate
     commit: b983156c5e994cc9892e0ce3e64e17e0
+    digest: shake256:436ce453801917c11bc7b21d66bcfae87da2aceb804a041487be1e51dc9fbc219e61ea6a552db7a7aa6d63bb5efd0f3ed5fe3d4c42d4f750d0eb35f14144e3b6
   - remote: buf.build
     owner: googleapis
     repository: googleapis
     commit: 4ed3bc159a8b4ac68fe253218760d035
+    digest: shake256:7149cf5e9955c692d381e557830555d4e93f205a0f1b8e2dfdae46d029369aa3fc1980e35df0d310f7cc3b622f93e19ad276769a283a967dd3065ddfd3a40e13
+  - remote: buf.build
+    owner: grpc-ecosystem
+    repository: grpc-gateway
+    commit: 4c5ba75caaf84e928b7137ae5c18c26a
+    digest: shake256:e174ad9408f3e608f6157907153ffec8d310783ee354f821f57178ffbeeb8faa6bb70b41b61099c1783c82fe16210ebd1279bc9c9ee6da5cffba9f0e675b8b99
   - remote: buf.build
     owner: kratos-go
     repository: kratos
     commit: e1d52e944e3845c6862a566db322432d
+    digest: shake256:f7a0c398ccbb951aa222af7f1d822bfc5a9978fbaef040679e7d85c98568198c88e0727f6d2837a3e0fbb853d3ece0f9c3c8e92a90709e05a3bf69144137b48e

app/controlplane/api/buf.yaml

@@ -3,9 +3,10 @@ breaking:
   use:
     - FILE
 deps:
-  - buf.build/googleapis/googleapis
-  - buf.build/bufbuild/protovalidate
-  - buf.build/kratos-go/kratos
+  - buf.build/googleapis/googleapis:4ed3bc159a8b4ac68fe253218760d035
+  - buf.build/bufbuild/protovalidate:b983156c5e994cc9892e0ce3e64e17e0
+  - buf.build/kratos-go/kratos:e1d52e944e3845c6862a566db322432d
+  - buf.build/grpc-ecosystem/grpc-gateway:v2.26.3
 lint:
   use:
     - DEFAULT

app/controlplane/api/controlplane/v1/api_token.proto

@@ -49,10 +49,10 @@ message APITokenServiceRevokeRequest {
   string name = 1 [(buf.validate.field) = {
     // NOTE: validations can not be shared yet https://github.com/bufbuild/protovalidate/issues/51
     cel: {
-      message: "must contain only lowercase letters, numbers, and hyphens.",
-      expression: "this.matches('^[a-z0-9]([-a-z0-9]*[a-z0-9])?$')",
-      id: "name.dns-1123",
-    },
+      message: "must contain only lowercase letters, numbers, and hyphens."
+      expression: "this.matches('^[a-z0-9]([-a-z0-9]*[a-z0-9])?$')"
+      id: "name.dns-1123"
+    }
   }];
 }
 

app/controlplane/api/controlplane/v1/auth.proto

@@ -16,15 +16,15 @@
 syntax = "proto3";
 
 package controlplane.v1;
+
 option go_package = "github.com/chainloop-dev/chainloop/app/controlplane/api/controlplane/v1;v1";
 
 service AuthService {
-	rpc DeleteAccount (AuthServiceDeleteAccountRequest) returns (AuthServiceDeleteAccountResponse);
+  rpc DeleteAccount(AuthServiceDeleteAccountRequest) returns (AuthServiceDeleteAccountResponse);
 }
 
 // AuthServiceDeleteAccountResponse is the response for the DeleteAccount method.
 message AuthServiceDeleteAccountRequest {}
 
 // AuthServiceDeleteAccountResponse is the response for the DeleteAccount method.
-message AuthServiceDeleteAccountResponse {
-}
+message AuthServiceDeleteAccountResponse {}

app/controlplane/api/controlplane/v1/cas_backends.proto

@@ -63,10 +63,10 @@ message CASBackendServiceUpdateRequest {
   string name = 1 [(buf.validate.field) = {
     // NOTE: validations can not be shared yet https://github.com/bufbuild/protovalidate/issues/51
     cel: {
-      message: "must contain only lowercase letters, numbers, and hyphens.",
-      expression: "this.matches('^[a-z0-9]([-a-z0-9]*[a-z0-9])?$')",
-      id: "name.dns-1123",
-    },
+      message: "must contain only lowercase letters, numbers, and hyphens."
+      expression: "this.matches('^[a-z0-9]([-a-z0-9]*[a-z0-9])?$')"
+      id: "name.dns-1123"
+    }
   }];
   // Description
   string description = 2;
@@ -84,10 +84,10 @@ message CASBackendServiceDeleteRequest {
   string name = 1 [(buf.validate.field) = {
     // NOTE: validations can not be shared yet https://github.com/bufbuild/protovalidate/issues/51
     cel: {
-      message: "must contain only lowercase letters, numbers, and hyphens.",
-      expression: "this.matches('^[a-z0-9]([-a-z0-9]*[a-z0-9])?$')",
-      id: "name.dns-1123",
-    },
+      message: "must contain only lowercase letters, numbers, and hyphens."
+      expression: "this.matches('^[a-z0-9]([-a-z0-9]*[a-z0-9])?$')"
+      id: "name.dns-1123"
+    }
   }];
 }
 

app/controlplane/api/controlplane/v1/cas_redirect.proto

@@ -17,13 +17,13 @@ syntax = "proto3";
 
 package controlplane.v1;
 
-option go_package = "github.com/chainloop-dev/chainloop/app/controlplane/api/controlplane/v1;v1";
-
 import "buf/validate/validate.proto";
 
+option go_package = "github.com/chainloop-dev/chainloop/app/controlplane/api/controlplane/v1;v1";
+
 service CASRedirectService {
-	// Retrieve the URL to download an artifact in CAS
-	rpc GetDownloadURL (GetDownloadURLRequest) returns (GetDownloadURLResponse);
+  // Retrieve the URL to download an artifact in CAS
+  rpc GetDownloadURL(GetDownloadURLRequest) returns (GetDownloadURLResponse);
 }
 
 message GetDownloadURLRequest {
@@ -32,7 +32,7 @@ message GetDownloadURLRequest {
 
 message GetDownloadURLResponse {
   Result result = 1;
-  
+
   message Result {
     string url = 2;
   }

app/controlplane/api/controlplane/v1/openapi_metadata.proto

@@ -0,0 +1,42 @@
+syntax = "proto3";
+
+package controlplane.v1;
+
+import "protoc-gen-openapiv2/options/annotations.proto";
+
+option go_package = "github.com/chainloop-dev/chainloop/app/controlplane/api/controlplane/v1;v1";
+option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
+  info: {
+    title: "Chainloop Controlplane API"
+    version: "1.0"
+    contact: {
+      name: "Chainloop Support"
+      url: "https://chainloop.dev"
+      email: "support@chainloop.dev"
+    }
+    terms_of_service: "https://chainloop.dev/terms"
+  }
+  schemes: [HTTPS]
+  consumes: ["application/json"]
+  host: "cp.chainloop.dev"
+  security_definitions: {
+    security: {
+      key: "bearerToken"
+      value: {
+        name: "Authorization"
+        description: "Bearer token for authentication"
+        type: TYPE_API_KEY
+        in: IN_HEADER
+      }
+    }
+  }
+  security: [
+    {
+      security_requirement: {key: "bearerToken"}
+    }
+  ]
+  external_docs: {
+    description: "Chainloop Official Documentation"
+    url: "https://docs.chainloop.dev"
+  }
+};

app/controlplane/api/controlplane/v1/org_invitation.proto

@@ -17,9 +17,9 @@ syntax = "proto3";
 
 package controlplane.v1;
 
+import "buf/validate/validate.proto";
 import "controlplane/v1/response_messages.proto";
 import "google/protobuf/timestamp.proto";
-import "buf/validate/validate.proto";
 
 option go_package = "github.com/chainloop-dev/chainloop/app/controlplane/api/controlplane/v1;v1";