docs: Generate API docs for connect-go API

Makefile

@@ -69,13 +69,14 @@ lint: go/lint helm/lint buf/lint goreleaser/lint ## Lint Go, Helm and protobuf
 test: go/test ## Run unit tests
 
 .PHONY: generate
-generate: $(BIN)/buf $(BIN)/protoc-gen-go $(BIN)/protoc-gen-go-vtproto $(BIN)/protoc-gen-openapiv2 $(BIN)/protoc-gen-grpc-gateway $(BIN)/protoc-gen-connect-go $(BIN)/protoc-gen-connect-go-mux $(BIN)/gomodifytags ## Regenerate protobuf
+generate: $(BIN)/buf $(BIN)/protoc-gen-go $(BIN)/protoc-gen-go-vtproto $(BIN)/protoc-gen-openapiv2 $(BIN)/protoc-gen-grpc-gateway $(BIN)/protoc-gen-connect-go $(BIN)/protoc-gen-connect-go-mux $(BIN)/gomodifytags $(BIN)/protoc-gen-connect-openapi ## Regenerate protobuf
 	rm -Rf api/openapiv2/gen/ api/gen
 	find pkg/ \( -name \*.pb.go -o -name \*.connect\*.go \) -delete
 	cd api/ && PATH=$(BIN) $(BIN)/buf generate
 	cd pkg && PATH=$(BIN) $(BIN)/buf generate
 	PATH="$(BIN):$(PATH)" ./tools/add-parquet-tags.sh
 	go run ./tools/doc-generator/ ./docs/sources/configure-server/reference-configuration-parameters/index.template > docs/sources/configure-server/reference-configuration-parameters/index.md
+	go run ./tools/api-docs-generator/
 
 .PHONY: buf/lint
 buf/lint: $(BIN)/buf
@@ -347,6 +348,10 @@ $(BIN)/protoc-gen-grpc-gateway: Makefile go.mod
 	@mkdir -p $(@D)
 	GOBIN=$(abspath $(@D)) $(GO) install github.com/grpc-ecosystem/grpc-gateway/v2/[email protected]
 
+$(BIN)/protoc-gen-connect-openapi: Makefile go.mod
+	@mkdir -p $(@D)
+	GOBIN=$(abspath $(@D)) $(GO) install github.com/sudorandom/[email protected]
+
 $(BIN)/gomodifytags: Makefile go.mod
 	@mkdir -p $(@D)
 	GOBIN=$(abspath $(@D)) $(GO) install github.com/fatih/[email protected]

api/buf.gen.yaml

@@ -5,6 +5,7 @@ managed:
     default: github.com/grafana/pyroscope/api/gen/proto/go
     except:
       - buf.build/googleapis/googleapis
+      - buf.build/gnostic/gnostic
 
 plugins:
   - name: go
@@ -34,3 +35,11 @@ plugins:
     out: openapiv2/gen/
     strategy: all
     opt: allow_merge=true,merge_file_name=phlare
+
+  - name: connect-openapi
+    out: connect-openapi/gen/
+    opt:
+      #- debug
+      - content-types=json
+      - trim-unused-types
+      - base=connect-openapi/base.yaml

api/buf.lock

@@ -1,11 +1,18 @@
 # Generated by buf. DO NOT EDIT.
 version: v1
 deps:
+  - remote: buf.build
+    owner: gnostic
+    repository: gnostic
+    commit: 087bc8072ce44e339f213209e4d57bf0
+    digest: shake256:4689c26f0460fea84c4c277c1b9c7e7d657388c5b4116d1065f907a92100ffbea87de05bbd138a0166411361e1f6ce063b4c0c6002358d39710f3c4a8de788d5
   - remote: buf.build
     owner: googleapis
     repository: googleapis
-    commit: 8d7204855ec14631a499bd7393ce1970
+    commit: 61b203b9a9164be9a834f58c37be6f62
+    digest: shake256:e619113001d6e284ee8a92b1561e5d4ea89a47b28bf0410815cb2fa23914df8be9f1a6a98dcf069f5bc2d829a2cfb1ac614863be45cd4f8a5ad8606c5f200224
   - remote: buf.build
     owner: grpc-ecosystem
     repository: grpc-gateway
-    commit: bc28b723cd774c32b6fbc77621518765
+    commit: 4c5ba75caaf84e928b7137ae5c18c26a
+    digest: shake256:e174ad9408f3e608f6157907153ffec8d310783ee354f821f57178ffbeeb8faa6bb70b41b61099c1783c82fe16210ebd1279bc9c9ee6da5cffba9f0e675b8b99

api/buf.yaml

@@ -9,3 +9,4 @@ breaking:
 deps:
   - buf.build/googleapis/googleapis
   - buf.build/grpc-ecosystem/grpc-gateway
+  - buf.build/gnostic/gnostic

api/connect-openapi/base.yaml

@@ -0,0 +1,10 @@
+openapi: 3.1.0
+info:
+  title: Pyroscope API
+  description: "Pyroscope API definitions"
+  version: v1.0.0
+tags:
+  - name: scope/public
+    description: This operation is considered part of the public API scope
+  - name: scope/internal
+    description: This operation is considered part of the interal API scope. There are no stability guaraentees when using those APIs.

api/connect-openapi/gen/adhocprofiles/v1/adhocprofiles.openapi.yaml

@@ -0,0 +1,302 @@
+openapi: 3.1.0
+info:
+  title: adhocprofiles.v1
+  version: v1.0.0
+tags:
+  - name: scope/public
+    description: This operation is considered part of the public API scope
+  - name: scope/internal
+    description: This operation is considered part of the interal API scope. There are no stability guaraentees when using those APIs.
+  - name: adhocprofiles.v1.AdHocProfileService
+paths:
+  /adhocprofiles.v1.AdHocProfileService/Get:
+    post:
+      tags:
+        - adhocprofiles.v1.AdHocProfileService
+      summary: Retrieves a profile from the underlying store by id and an optional sample type. The response is similar to the one  for the upload method.
+      description: |-
+        Retrieves a profile from the underlying store by id and an optional sample type. The response is similar to the one
+         for the upload method.
+      operationId: adhocprofiles.v1.AdHocProfileService.Get
+      parameters:
+        - name: Connect-Protocol-Version
+          in: header
+          required: true
+          schema:
+            $ref: '#/components/schemas/connect-protocol-version'
+        - name: Connect-Timeout-Ms
+          in: header
+          schema:
+            $ref: '#/components/schemas/connect-timeout-header'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/adhocprofiles.v1.AdHocProfilesGetRequest'
+        required: true
+      responses:
+        default:
+          description: Error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/connect.error'
+        "200":
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/adhocprofiles.v1.AdHocProfilesGetResponse'
+  /adhocprofiles.v1.AdHocProfileService/List:
+    post:
+      tags:
+        - adhocprofiles.v1.AdHocProfileService
+      summary: Retrieves a list of profiles found in the underlying store.
+      description: Retrieves a list of profiles found in the underlying store.
+      operationId: adhocprofiles.v1.AdHocProfileService.List
+      parameters:
+        - name: Connect-Protocol-Version
+          in: header
+          required: true
+          schema:
+            $ref: '#/components/schemas/connect-protocol-version'
+        - name: Connect-Timeout-Ms
+          in: header
+          schema:
+            $ref: '#/components/schemas/connect-timeout-header'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/adhocprofiles.v1.AdHocProfilesListRequest'
+        required: true
+      responses:
+        default:
+          description: Error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/connect.error'
+        "200":
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/adhocprofiles.v1.AdHocProfilesListResponse'
+  /adhocprofiles.v1.AdHocProfileService/Upload:
+    post:
+      tags:
+        - adhocprofiles.v1.AdHocProfileService
+      summary: Upload a profile to the underlying store. The request contains a name and a base64 encoded pprof file. The response  contains a generated unique identifier, a flamegraph and a list of found sample types within the profile.
+      description: |-
+        Upload a profile to the underlying store. The request contains a name and a base64 encoded pprof file. The response
+         contains a generated unique identifier, a flamegraph and a list of found sample types within the profile.
+      operationId: adhocprofiles.v1.AdHocProfileService.Upload
+      parameters:
+        - name: Connect-Protocol-Version
+          in: header
+          required: true
+          schema:
+            $ref: '#/components/schemas/connect-protocol-version'
+        - name: Connect-Timeout-Ms
+          in: header
+          schema:
+            $ref: '#/components/schemas/connect-timeout-header'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/adhocprofiles.v1.AdHocProfilesUploadRequest'
+        required: true
+      responses:
+        default:
+          description: Error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/connect.error'
+        "200":
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/adhocprofiles.v1.AdHocProfilesGetResponse'
+components:
+  schemas:
+    adhocprofiles.v1.AdHocProfilesGetRequest:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+          description: The unique identifier of the profile.
+        profileType:
+          type: string
+          title: profile_type
+          description: The desired profile type (e.g., cpu, samples) for the returned flame graph. If omitted the first profile is returned.
+          nullable: true
+        maxNodes:
+          type:
+            - integer
+            - string
+          title: max_nodes
+          format: int64
+          description: Max nodes can be used to truncate the response.
+          nullable: true
+      title: AdHocProfilesGetRequest
+      additionalProperties: false
+    adhocprofiles.v1.AdHocProfilesGetResponse:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        name:
+          type: string
+          title: name
+        uploadedAt:
+          type:
+            - integer
+            - string
+          title: uploaded_at
+          format: int64
+          description: timestamp in milliseconds
+        profileType:
+          type: string
+          title: profile_type
+        profileTypes:
+          type: array
+          items:
+            type: string
+          title: profile_types
+          description: |-
+            Some profiles formats (like pprof) can contain multiple profile (sample) types inside. One of these can be passed
+             in the Get request using the profile_type field.
+        flamebearerProfile:
+          type: string
+          title: flamebearer_profile
+      title: AdHocProfilesGetResponse
+      additionalProperties: false
+    adhocprofiles.v1.AdHocProfilesListRequest:
+      type: object
+      title: AdHocProfilesListRequest
+      additionalProperties: false
+    adhocprofiles.v1.AdHocProfilesListResponse:
+      type: object
+      properties:
+        profiles:
+          type: array
+          items:
+            $ref: '#/components/schemas/adhocprofiles.v1.AdHocProfilesProfileMetadata'
+          title: profiles
+      title: AdHocProfilesListResponse
+      additionalProperties: false
+    adhocprofiles.v1.AdHocProfilesProfileMetadata:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        name:
+          type: string
+          title: name
+        uploadedAt:
+          type:
+            - integer
+            - string
+          title: uploaded_at
+          format: int64
+          description: timestamp in milliseconds
+      title: AdHocProfilesProfileMetadata
+      additionalProperties: false
+    adhocprofiles.v1.AdHocProfilesUploadRequest:
+      type: object
+      properties:
+        name:
+          type: string
+          title: name
+          description: This is typically the file name and it serves as a human readable name for the profile.
+        profile:
+          type: string
+          title: profile
+          description: This is the profile encoded in base64. The supported formats are pprof, json, collapsed and perf-script.
+        maxNodes:
+          type:
+            - integer
+            - string
+          title: max_nodes
+          format: int64
+          description: Max nodes can be used to truncate the response.
+          nullable: true
+      title: AdHocProfilesUploadRequest
+      additionalProperties: false
+    connect-protocol-version:
+      type: number
+      title: Connect-Protocol-Version
+      enum:
+        - 1
+      description: Define the version of the Connect protocol
+      const: 1
+    connect-timeout-header:
+      type: number
+      title: Connect-Timeout-Ms
+      description: Define the timeout, in ms
+    connect.error:
+      type: object
+      properties:
+        code:
+          type: string
+          examples:
+            - not_found
+          enum:
+            - canceled
+            - unknown
+            - invalid_argument
+            - deadline_exceeded
+            - not_found
+            - already_exists
+            - permission_denied
+            - resource_exhausted
+            - failed_precondition
+            - aborted
+            - out_of_range
+            - unimplemented
+            - internal
+            - unavailable
+            - data_loss
+            - unauthenticated
+          description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
+        message:
+          type: string
+          description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
+        details:
+          type: array
+          items:
+            $ref: '#/components/schemas/connect.error_details.Any'
+          description: A list of messages that carry the error details. There is no limit on the number of messages.
+      title: Connect Error
+      additionalProperties: true
+      description: 'Error type returned by Connect: https://connectrpc.com/docs/go/errors/#http-representation'
+    connect.error_details.Any:
+      type: object
+      properties:
+        type:
+          type: string
+          description: 'A URL that acts as a globally unique identifier for the type of the serialized message. For example: `type.googleapis.com/google.rpc.ErrorInfo`. This is used to determine the schema of the data in the `value` field and is the discriminator for the `debug` field.'
+        value:
+          type: string
+          format: binary
+          description: The Protobuf message, serialized as bytes and base64-encoded. The specific message type is identified by the `type` field.
+        debug:
+          oneOf:
+            - type: object
+              title: Any
+              additionalProperties: true
+              description: Detailed error information.
+          discriminator:
+            propertyName: type
+          title: Debug
+          description: Deserialized error detail payload. The 'type' field indicates the schema. This field is for easier debugging and should not be relied upon for application logic.
+      additionalProperties: true
+      description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message, with an additional debug field for ConnectRPC error details.
+security: []