Skip to content

Commit a0a5d02

Browse files
simonswinesimonswine
committed
WIP: Generate API docs for connect-go API
1 parent c67b86e commit a0a5d02

38 files changed

+12203
-399
lines changed

‎Makefile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ generate: $(BIN)/buf $(BIN)/protoc-gen-go $(BIN)/protoc-gen-go-vtproto $(BIN)/pr
7070
cd pkg && PATH=$(BIN) $(BIN)/buf generate
7171
PATH="$(BIN):$(PATH)" ./tools/add-parquet-tags.sh
7272
go run ./tools/doc-generator/ ./docs/sources/configure-server/reference-configuration-parameters/index.template > docs/sources/configure-server/reference-configuration-parameters/index.md
73+
go run ./tools/api-docs-generator -input=api/connect-openapi/gen -output=docs/api-reference.md
7374

7475
.PHONY: buf/lint
7576
buf/lint: $(BIN)/buf

‎api/buf.gen.yaml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ managed:
55
default: github.com/grafana/pyroscope/api/gen/proto/go
66
except:
77
- buf.build/googleapis/googleapis
8+
- buf.build/gnostic/gnostic
89

910
plugins:
1011
- name: go
@@ -34,3 +35,11 @@ plugins:
3435
out: openapiv2/gen/
3536
strategy: all
3637
opt: allow_merge=true,merge_file_name=phlare
38+
39+
- name: connect-openapi
40+
out: connect-openapi/gen/
41+
opt:
42+
#- debug
43+
- content-types=json
44+
- trim-unused-types
45+
- base=connect-openapi/base.yaml

‎api/buf.lock‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,18 @@
11
# Generated by buf. DO NOT EDIT.
22
version: v1
33
deps:
4+
- remote: buf.build
5+
owner: gnostic
6+
repository: gnostic
7+
commit: 087bc8072ce44e339f213209e4d57bf0
8+
digest: shake256:4689c26f0460fea84c4c277c1b9c7e7d657388c5b4116d1065f907a92100ffbea87de05bbd138a0166411361e1f6ce063b4c0c6002358d39710f3c4a8de788d5
49
- remote: buf.build
510
owner: googleapis
611
repository: googleapis
7-
commit: 8d7204855ec14631a499bd7393ce1970
12+
commit: 61b203b9a9164be9a834f58c37be6f62
13+
digest: shake256:e619113001d6e284ee8a92b1561e5d4ea89a47b28bf0410815cb2fa23914df8be9f1a6a98dcf069f5bc2d829a2cfb1ac614863be45cd4f8a5ad8606c5f200224
814
- remote: buf.build
915
owner: grpc-ecosystem
1016
repository: grpc-gateway
11-
commit: bc28b723cd774c32b6fbc77621518765
17+
commit: 4c5ba75caaf84e928b7137ae5c18c26a
18+
digest: shake256:e174ad9408f3e608f6157907153ffec8d310783ee354f821f57178ffbeeb8faa6bb70b41b61099c1783c82fe16210ebd1279bc9c9ee6da5cffba9f0e675b8b99

‎api/buf.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,4 @@ breaking:
99
deps:
1010
- buf.build/googleapis/googleapis
1111
- buf.build/grpc-ecosystem/grpc-gateway
12+
- buf.build/gnostic/gnostic

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

Lines changed: 302 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,302 @@
1+
openapi: 3.1.0
2+
info:
3+
title: adhocprofiles.v1
4+
version: v1.0.0
5+
tags:
6+
- name: scope/public
7+
description: This operation is considered part of the public API scope
8+
- name: scope/internal
9+
description: This operation is considered part of the interal API scope. There are no stability guaraentees when using those APIs.
10+
- name: adhocprofiles.v1.AdHocProfileService
11+
paths:
12+
/adhocprofiles.v1.AdHocProfileService/Upload:
13+
post:
14+
tags:
15+
- adhocprofiles.v1.AdHocProfileService
16+
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.
17+
description: |-
18+
Upload a profile to the underlying store. The request contains a name and a base64 encoded pprof file. The response
19+
contains a generated unique identifier, a flamegraph and a list of found sample types within the profile.
20+
operationId: adhocprofiles.v1.AdHocProfileService.Upload
21+
parameters:
22+
- name: Connect-Protocol-Version
23+
in: header
24+
required: true
25+
schema:
26+
$ref: '#/components/schemas/connect-protocol-version'
27+
- name: Connect-Timeout-Ms
28+
in: header
29+
schema:
30+
$ref: '#/components/schemas/connect-timeout-header'
31+
requestBody:
32+
content:
33+
application/json:
34+
schema:
35+
$ref: '#/components/schemas/adhocprofiles.v1.AdHocProfilesUploadRequest'
36+
required: true
37+
responses:
38+
default:
39+
description: Error
40+
content:
41+
application/json:
42+
schema:
43+
$ref: '#/components/schemas/connect.error'
44+
"200":
45+
description: Success
46+
content:
47+
application/json:
48+
schema:
49+
$ref: '#/components/schemas/adhocprofiles.v1.AdHocProfilesGetResponse'
50+
/adhocprofiles.v1.AdHocProfileService/Get:
51+
post:
52+
tags:
53+
- adhocprofiles.v1.AdHocProfileService
54+
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.
55+
description: |-
56+
Retrieves a profile from the underlying store by id and an optional sample type. The response is similar to the one
57+
for the upload method.
58+
operationId: adhocprofiles.v1.AdHocProfileService.Get
59+
parameters:
60+
- name: Connect-Protocol-Version
61+
in: header
62+
required: true
63+
schema:
64+
$ref: '#/components/schemas/connect-protocol-version'
65+
- name: Connect-Timeout-Ms
66+
in: header
67+
schema:
68+
$ref: '#/components/schemas/connect-timeout-header'
69+
requestBody:
70+
content:
71+
application/json:
72+
schema:
73+
$ref: '#/components/schemas/adhocprofiles.v1.AdHocProfilesGetRequest'
74+
required: true
75+
responses:
76+
default:
77+
description: Error
78+
content:
79+
application/json:
80+
schema:
81+
$ref: '#/components/schemas/connect.error'
82+
"200":
83+
description: Success
84+
content:
85+
application/json:
86+
schema:
87+
$ref: '#/components/schemas/adhocprofiles.v1.AdHocProfilesGetResponse'
88+
/adhocprofiles.v1.AdHocProfileService/List:
89+
post:
90+
tags:
91+
- adhocprofiles.v1.AdHocProfileService
92+
summary: Retrieves a list of profiles found in the underlying store.
93+
description: Retrieves a list of profiles found in the underlying store.
94+
operationId: adhocprofiles.v1.AdHocProfileService.List
95+
parameters:
96+
- name: Connect-Protocol-Version
97+
in: header
98+
required: true
99+
schema:
100+
$ref: '#/components/schemas/connect-protocol-version'
101+
- name: Connect-Timeout-Ms
102+
in: header
103+
schema:
104+
$ref: '#/components/schemas/connect-timeout-header'
105+
requestBody:
106+
content:
107+
application/json:
108+
schema:
109+
$ref: '#/components/schemas/adhocprofiles.v1.AdHocProfilesListRequest'
110+
required: true
111+
responses:
112+
default:
113+
description: Error
114+
content:
115+
application/json:
116+
schema:
117+
$ref: '#/components/schemas/connect.error'
118+
"200":
119+
description: Success
120+
content:
121+
application/json:
122+
schema:
123+
$ref: '#/components/schemas/adhocprofiles.v1.AdHocProfilesListResponse'
124+
components:
125+
schemas:
126+
adhocprofiles.v1.AdHocProfilesGetRequest:
127+
type: object
128+
properties:
129+
id:
130+
type: string
131+
title: id
132+
description: The unique identifier of the profile.
133+
profileType:
134+
type: string
135+
title: profile_type
136+
description: The desired profile type (e.g., cpu, samples) for the returned flame graph. If omitted the first profile is returned.
137+
nullable: true
138+
maxNodes:
139+
type:
140+
- integer
141+
- string
142+
title: max_nodes
143+
format: int64
144+
description: Max nodes can be used to truncate the response.
145+
nullable: true
146+
title: AdHocProfilesGetRequest
147+
additionalProperties: false
148+
adhocprofiles.v1.AdHocProfilesGetResponse:
149+
type: object
150+
properties:
151+
id:
152+
type: string
153+
title: id
154+
name:
155+
type: string
156+
title: name
157+
uploadedAt:
158+
type:
159+
- integer
160+
- string
161+
title: uploaded_at
162+
format: int64
163+
description: timestamp in milliseconds
164+
profileType:
165+
type: string
166+
title: profile_type
167+
profileTypes:
168+
type: array
169+
items:
170+
type: string
171+
title: profile_types
172+
description: |-
173+
Some profiles formats (like pprof) can contain multiple profile (sample) types inside. One of these can be passed
174+
in the Get request using the profile_type field.
175+
flamebearerProfile:
176+
type: string
177+
title: flamebearer_profile
178+
title: AdHocProfilesGetResponse
179+
additionalProperties: false
180+
adhocprofiles.v1.AdHocProfilesListRequest:
181+
type: object
182+
title: AdHocProfilesListRequest
183+
additionalProperties: false
184+
adhocprofiles.v1.AdHocProfilesListResponse:
185+
type: object
186+
properties:
187+
profiles:
188+
type: array
189+
items:
190+
$ref: '#/components/schemas/adhocprofiles.v1.AdHocProfilesProfileMetadata'
191+
title: profiles
192+
title: AdHocProfilesListResponse
193+
additionalProperties: false
194+
adhocprofiles.v1.AdHocProfilesProfileMetadata:
195+
type: object
196+
properties:
197+
id:
198+
type: string
199+
title: id
200+
name:
201+
type: string
202+
title: name
203+
uploadedAt:
204+
type:
205+
- integer
206+
- string
207+
title: uploaded_at
208+
format: int64
209+
description: timestamp in milliseconds
210+
title: AdHocProfilesProfileMetadata
211+
additionalProperties: false
212+
adhocprofiles.v1.AdHocProfilesUploadRequest:
213+
type: object
214+
properties:
215+
name:
216+
type: string
217+
title: name
218+
description: This is typically the file name and it serves as a human readable name for the profile.
219+
profile:
220+
type: string
221+
title: profile
222+
description: This is the profile encoded in base64. The supported formats are pprof, json, collapsed and perf-script.
223+
maxNodes:
224+
type:
225+
- integer
226+
- string
227+
title: max_nodes
228+
format: int64
229+
description: Max nodes can be used to truncate the response.
230+
nullable: true
231+
title: AdHocProfilesUploadRequest
232+
additionalProperties: false
233+
connect-protocol-version:
234+
type: number
235+
title: Connect-Protocol-Version
236+
enum:
237+
- 1
238+
description: Define the version of the Connect protocol
239+
const: 1
240+
connect-timeout-header:
241+
type: number
242+
title: Connect-Timeout-Ms
243+
description: Define the timeout, in ms
244+
connect.error:
245+
type: object
246+
properties:
247+
code:
248+
type: string
249+
examples:
250+
- not_found
251+
enum:
252+
- canceled
253+
- unknown
254+
- invalid_argument
255+
- deadline_exceeded
256+
- not_found
257+
- already_exists
258+
- permission_denied
259+
- resource_exhausted
260+
- failed_precondition
261+
- aborted
262+
- out_of_range
263+
- unimplemented
264+
- internal
265+
- unavailable
266+
- data_loss
267+
- unauthenticated
268+
description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
269+
message:
270+
type: string
271+
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.
272+
details:
273+
type: array
274+
items:
275+
$ref: '#/components/schemas/connect.error_details.Any'
276+
description: A list of messages that carry the error details. There is no limit on the number of messages.
277+
title: Connect Error
278+
additionalProperties: true
279+
description: 'Error type returned by Connect: https://connectrpc.com/docs/go/errors/#http-representation'
280+
connect.error_details.Any:
281+
type: object
282+
properties:
283+
type:
284+
type: string
285+
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.'
286+
value:
287+
type: string
288+
format: binary
289+
description: The Protobuf message, serialized as bytes and base64-encoded. The specific message type is identified by the `type` field.
290+
debug:
291+
oneOf:
292+
- type: object
293+
title: Any
294+
additionalProperties: true
295+
description: Detailed error information.
296+
discriminator:
297+
propertyName: type
298+
title: Debug
299+
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.
300+
additionalProperties: true
301+
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.
302+
security: []

0 commit comments

Comments
 (0)