Skip to content

Commit 20a2130

Browse files
sashamelentyevsashamelentyev
authored
Merge pull request #74 from ogen-go/exdocs
docs(README): add Generate OpenAPI block
2 parents 314e8c9 + 7e03d5b commit 20a2130

File tree

2 files changed

+298
-2
lines changed

2 files changed

+298
-2
lines changed

‎README.md

+298
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,301 @@ go install github.com/ogen-go/protoc-gen-oas/cmd/protoc-gen-oas
1515
```console
1616
protoc --oas_out=. service.proto
1717
```
18+
19+
# Features
20+
21+
- support [API annotations](https://github.com/googleapis/googleapis/blob/master/google/api/annotations.proto) in methods
22+
- support [field behavior](https://github.com/googleapis/googleapis/blob/master/google/api/field_behavior.proto) in message field description
23+
24+
# Generate OpenAPI
25+
26+
## Path param
27+
28+
```protobuf title="service.proto"
29+
syntax = "proto3";
30+
31+
package service.v1;
32+
33+
option go_package = "service/v1;service";
34+
35+
import "google/api/annotations.proto";
36+
37+
service Service {
38+
rpc GetItem(GetItemRequest) returns (Item) {
39+
option (google.api.http) = {
40+
get: "/api/v1/items/{id}" // <--
41+
};
42+
}
43+
}
44+
45+
message GetItemRequest {
46+
string id = 1; // <--
47+
}
48+
49+
message Item {
50+
string id = 1;
51+
string name = 2;
52+
}
53+
```
54+
55+
```yaml title="openapi.yaml"
56+
openapi: 3.1.0
57+
info:
58+
title: ""
59+
version: ""
60+
paths:
61+
/api/v1/items/{id}:
62+
get:
63+
operationId: getItem
64+
parameters:
65+
- name: id # <--
66+
in: path # <--
67+
schema:
68+
type: string
69+
responses:
70+
"200":
71+
description: service.v1.Service.GetItem response
72+
content:
73+
application/json:
74+
schema:
75+
$ref: '#/components/schemas/Item'
76+
components:
77+
schemas:
78+
Item:
79+
type: object
80+
properties:
81+
id:
82+
type: string
83+
name:
84+
type: string
85+
```
86+
87+
## Query param
88+
89+
```protobuf title="service.proto"
90+
syntax = "proto3";
91+
92+
package service.v1;
93+
94+
option go_package = "service/v1;service";
95+
96+
import "google/api/annotations.proto";
97+
98+
service Service {
99+
rpc GetItems(GetItemsRequest) returns (GetItemsResponse) {
100+
option (google.api.http) = {
101+
get: "/api/v1/items"
102+
};
103+
}
104+
}
105+
106+
message GetItemsRequest {
107+
int32 limit = 1; // <--
108+
int32 offset = 2; // <--
109+
}
110+
111+
message GetItemsResponse {
112+
repeated Item items = 1;
113+
int32 total_count = 2;
114+
}
115+
116+
message Item {
117+
string id = 1;
118+
string name = 2;
119+
}
120+
```
121+
122+
```yaml title="openapi.yaml"
123+
openapi: 3.1.0
124+
info:
125+
title: ""
126+
version: ""
127+
paths:
128+
/api/v1/items:
129+
get:
130+
operationId: getItems
131+
parameters:
132+
- name: limit # <--
133+
in: query # <--
134+
schema:
135+
type: integer
136+
format: int32
137+
- name: offset # <--
138+
in: query # <--
139+
schema:
140+
type: integer
141+
format: int32
142+
responses:
143+
"200":
144+
description: service.v1.Service.GetItems response
145+
content:
146+
application/json:
147+
schema:
148+
$ref: '#/components/schemas/GetItemsResponse'
149+
components:
150+
schemas:
151+
GetItemsResponse:
152+
type: object
153+
properties:
154+
items:
155+
type: array
156+
items:
157+
$ref: '#/components/schemas/Item'
158+
totalCount:
159+
type: integer
160+
format: int32
161+
Item:
162+
type: object
163+
properties:
164+
id:
165+
type: string
166+
name:
167+
type: string
168+
```
169+
170+
## Mark field as required
171+
172+
```protobuf title="service.proto"
173+
syntax = "proto3";
174+
175+
package service.v1;
176+
177+
option go_package = "service/v1;service";
178+
179+
import "google/api/annotations.proto";
180+
import "google/api/field_behavior.proto";
181+
import "google/protobuf/empty.proto";
182+
183+
service Service {
184+
rpc DeleteItem(DeleteItemRequest) returns (google.protobuf.Empty) {
185+
option (google.api.http) = {
186+
delete: "/api/v1/items/{id}"
187+
body: "*"
188+
};
189+
}
190+
}
191+
192+
message DeleteItemRequest {
193+
string id = 1 [(google.api.field_behavior) = REQUIRED]; // <--
194+
}
195+
```
196+
197+
```yaml title="openapi.yaml"
198+
openapi: 3.1.0
199+
info:
200+
title: ""
201+
version: ""
202+
paths:
203+
/api/v1/items/{id}:
204+
delete:
205+
operationId: deleteItem
206+
parameters:
207+
- name: id
208+
in: path
209+
required: true
210+
schema:
211+
type: string
212+
responses:
213+
"200":
214+
description: service.v1.Service.DeleteItem response
215+
content:
216+
application/json:
217+
schema:
218+
$ref: '#/components/schemas/Empty'
219+
components:
220+
schemas:
221+
CreateItemRequest:
222+
type: object
223+
properties:
224+
name:
225+
type: string
226+
required: # <--
227+
- name # <--
228+
Empty:
229+
type: object
230+
```
231+
232+
## Mark field as deprecated
233+
234+
```protobuf title="service.proto"
235+
syntax = "proto3";
236+
237+
package service.v1;
238+
239+
option go_package = "service/v1;service";
240+
241+
import "google/api/annotations.proto";
242+
243+
service Service {
244+
rpc GetItems(GetItemsRequest) returns (GetItemsResponse) {
245+
option (google.api.http) = {
246+
get: "/api/v1/items"
247+
};
248+
}
249+
}
250+
251+
message GetItemsRequest {
252+
int32 limit = 1;
253+
int32 offset = 2 [deprecated = true]; // <--
254+
}
255+
256+
message GetItemsResponse {
257+
repeated Item items = 1;
258+
int32 total_count = 2;
259+
}
260+
261+
message Item {
262+
string id = 1;
263+
string name = 2 [deprecated = true]; // <--
264+
}
265+
```
266+
267+
```yaml title="openapi.yaml"
268+
openapi: 3.1.0
269+
info:
270+
title: ""
271+
version: ""
272+
paths:
273+
/api/v1/items:
274+
get:
275+
operationId: getItems
276+
parameters:
277+
- name: limit
278+
in: query
279+
schema:
280+
type: integer
281+
format: int32
282+
- name: offset
283+
in: query
284+
schema:
285+
type: integer
286+
format: int32
287+
deprecated: true # <--
288+
responses:
289+
"200":
290+
description: service.v1.Service.GetItems response
291+
content:
292+
application/json:
293+
schema:
294+
$ref: '#/components/schemas/GetItemsResponse'
295+
components:
296+
schemas:
297+
GetItemsResponse:
298+
type: object
299+
properties:
300+
items:
301+
type: array
302+
items:
303+
$ref: '#/components/schemas/Item'
304+
totalCount:
305+
type: integer
306+
format: int32
307+
Item:
308+
type: object
309+
properties:
310+
id:
311+
type: string
312+
name:
313+
type: string
314+
deprecated: true # <--
315+
```

‎protoc-gen-oas.go

-2
This file was deleted.

0 commit comments

Comments
 (0)