Skip to content

Commit 4a33644

Browse files
VojtechVitekVojtechVitek
authored
Downgrade back to OpenAPI 3.0.0, tooling is not yet ready (#27)
The tooling around OpenAPI is not yet ready for 3.2.0. The swagger-ui or redocly both error out.
1 parent 1ddac31 commit 4a33644

5 files changed

Lines changed: 135 additions & 42 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
# webrpc OpenAPI 3.2.0 (Swagger) generator <!-- omit in toc -->
1+
# webrpc OpenAPI 3.0.0 (Swagger) generator <!-- omit in toc -->
22

33
This repo contains the templates used by the [webrpc-gen](https://github.com/webrpc/webrpc) cli to code-generate OpenAPI documentation from webrpc schema.
44

5-
- [Generate OpenAPI 3.2.0 YAML file](#generate-openapi-320-yaml-file)
5+
- [Generate OpenAPI 3.0.0 YAML file](#generate-openapi-300-yaml-file)
66
- [Set custom template variables](#set-custom-template-variables)
77
- [Open in Swagger UI](#open-in-swagger-ui)
88
- [Build static HTML documentation with Redocly](#build-static-html-documentation-with-redocly)
@@ -12,7 +12,7 @@ This repo contains the templates used by the [webrpc-gen](https://github.com/web
1212
- [Authors](#authors)
1313
- [License](#license)
1414

15-
# Generate OpenAPI 3.2.0 YAML file
15+
# Generate OpenAPI 3.0.0 YAML file
1616
```bash
1717
webrpc-gen -schema=./proto.ridl -target=openapi -out petstore.gen.yaml
1818
```

‎_examples/Makefile‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ generate:
2222
} \
2323
}"; \
2424
webrpc-gen \
25-
-schema=./proto.ridl \
25+
-schema=./api.ridl \
2626
-target=../ \
2727
-out=./openapi.gen.yaml \
2828
-title="Example webrpc API" \
@@ -37,4 +37,4 @@ diff:
3737

3838
swagger:
3939
@echo "Swagger UI is available at http://localhost:8088"
40-
docker run -p 8088:8080 -v $$(pwd):/docs -e SWAGGER_JSON=/docs/openapi.gen.yaml swaggerapi/swagger-ui
40+
docker run -p 8088:8080 -v $$(pwd):/docs -e SWAGGER_JSON=/docs/openapi.gen.yaml swaggerapi/swagger-ui:v5.31.0

_examples/proto.ridl renamed to _examples/api.ridl

Lines changed: 44 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,44 @@ webrpc = v1 # version of webrpc schema format (ridl or json)
33
name = example # name of your backend app
44
version = v0.0.1 # version of your schema
55

6+
service ExampleService
7+
@deprecated
8+
- Ping()
9+
10+
@deprecated:"Use GetUserV2 instead."
11+
@auth:JWT
12+
- GetUser(header: map<string,string>, userID: uint64) => (code: uint32, user: User)
13+
14+
# GetUserV2 returns user based on given userID.
15+
# Replaces GetUser endpoint.
16+
@auth:JWT
17+
- GetUserV2(header: map<string,string>, userID: uint64) => (code: uint32, user: User, profilePicture: string)
18+
19+
# FindUser searches for a user using the given search filter.
20+
#
21+
# The filters are q (string) and active (bool).
22+
#
23+
# The minimal length of the "q" filter is 3 characters.
24+
@auth:JWT
25+
- FindUser(s: SearchFilter) => (name: string, user: User)
26+
27+
# ListUsers returns all users.
28+
@auth:JWT
29+
- ListUsers() => (users: []User)
30+
31+
- GetComplex() => (complex: ComplexType)
32+
- GetAllOptional() => (optional: Optional)
33+
34+
- StreamUserNotifications(StreamNotificationsRequest) => stream (StreamNotificationsResponse)
35+
36+
service AdminService
37+
@auth:JWT
38+
- ListUsers() => (users: []User)
39+
40+
error 100 RateLimited "too many requests" HTTP 429
41+
error 101 DatabaseDown "service outage" HTTP 503
42+
43+
644
enum Kind: uint32
745
- USER
846
- ADMIN
@@ -44,38 +82,11 @@ struct Optional
4482
- name?: string
4583
- email?: string
4684

47-
service ExampleService
48-
@deprecated
49-
- Ping()
50-
51-
@deprecated:"Use GetUserV2 instead."
52-
@auth:JWT
53-
- GetUser(header: map<string,string>, userID: uint64) => (code: uint32, user: User)
54-
55-
# GetUserV2 returns user based on given userID.
56-
# Replaces GetUser endpoint.
57-
@auth:JWT
58-
- GetUserV2(header: map<string,string>, userID: uint64) => (code: uint32, user: User, profilePicture: string)
85+
struct StreamNotificationsRequest
5986

60-
# FindUser searches for a user using the given search filter.
61-
#
62-
# The filters are q (string) and active (bool).
63-
#
64-
# The minimal length of the "q" filter is 3 characters.
65-
@auth:JWT
66-
- FindUser(s: SearchFilter) => (name: string, user: User)
67-
68-
# ListUsers returns all users.
69-
@auth:JWT
70-
- ListUsers() => (users: []User)
71-
72-
- GetComplex() => (complex: ComplexType)
73-
- GetAllOptional() => (optional: Optional)
74-
75-
service AdminService
76-
@auth:JWT
77-
- ListUsers() => (users: []User)
78-
79-
error 100 RateLimited "too many requests" HTTP 429
80-
error 101 DatabaseDown "service outage" HTTP 503
87+
struct StreamNotificationsResponse
88+
- notification: Notification
8189

90+
struct Notification
91+
- message: string
92+
- timestamp: timestamp

‎_examples/openapi.gen.yaml‎

Lines changed: 76 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
# example v0.0.1 9814b024890e4f9bf0fb6406686c29bcc402b24a
1+
# example v0.0.1 55eeccc8db95e08d65f0da63acfdcbd92cc1e6fa
22
# --
33
# Code generated by webrpc-gen@v0.31.0 with ../ generator; DO NOT EDIT
44
#
5-
# webrpc-gen -schema=./proto.ridl -target=../ -out=./openapi.gen.yaml -title=Example webrpc API -apiVersion=v22.11.8 -serverUrl=https://api.example.com -serverDescription=Production -securityAnnotation=@auth -securitySchemes={ 'ApiKeyAuth': { 'type': 'apiKey', 'in': 'header', 'description': 'Project access key for authenticating requests', 'name': 'X-Access-Key' }, 'ServiceAuth': { 'type': 'apiKey', 'in': 'header', 'description': 'Project access key for authenticating requests', 'name': 'X-Access-Key' } }
6-
openapi: 3.2.0
5+
# webrpc-gen -schema=./api.ridl -target=../ -out=./openapi.gen.yaml -title=Example webrpc API -apiVersion=v22.11.8 -serverUrl=https://api.example.com -serverDescription=Production -securityAnnotation=@auth -securitySchemes={ 'ApiKeyAuth': { 'type': 'apiKey', 'in': 'header', 'description': 'Project access key for authenticating requests', 'name': 'X-Access-Key' }, 'ServiceAuth': { 'type': 'apiKey', 'in': 'header', 'description': 'Project access key for authenticating requests', 'name': 'X-Access-Key' } }
6+
openapi: 3.0.0
77
info:
88
title: 'Example webrpc API'
99
version: 'v22.11.8'
@@ -411,6 +411,25 @@ components:
411411
type: string
412412
email:
413413
type: string
414+
StreamNotificationsRequest:
415+
type: object
416+
StreamNotificationsResponse:
417+
type: object
418+
required:
419+
- notification
420+
properties:
421+
notification:
422+
$ref: '#/components/schemas/Notification'
423+
Notification:
424+
type: object
425+
required:
426+
- message
427+
- timestamp
428+
properties:
429+
message:
430+
type: string
431+
timestamp:
432+
type: string
414433
ExampleService_Ping_Request:
415434
type: object
416435
ExampleService_GetUser_Request:
@@ -444,6 +463,11 @@ components:
444463
type: object
445464
ExampleService_GetAllOptional_Request:
446465
type: object
466+
ExampleService_StreamUserNotifications_Request:
467+
type: object
468+
properties:
469+
streamNotificationsRequest:
470+
$ref: '#/components/schemas/StreamNotificationsRequest'
447471
ExampleService_Ping_Response:
448472
type: object
449473
ExampleService_GetUser_Response:
@@ -487,6 +511,11 @@ components:
487511
properties:
488512
optional:
489513
$ref: '#/components/schemas/Optional'
514+
ExampleService_StreamUserNotifications_Response:
515+
type: object
516+
properties:
517+
streamNotificationsResponse:
518+
$ref: '#/components/schemas/StreamNotificationsResponse'
490519
AdminService_ListUsers_Request:
491520
type: object
492521
AdminService_ListUsers_Response:
@@ -803,6 +832,50 @@ paths:
803832
- $ref: '#/components/schemas/ErrorWebrpcServerPanic'
804833
- $ref: '#/components/schemas/ErrorWebrpcInternalError'
805834
- $ref: '#/components/schemas/ErrorDatabaseDown'
835+
/rpc/ExampleService/StreamUserNotifications:
836+
post:
837+
operationId: ExampleService-StreamUserNotifications
838+
tags: ["ExampleService"]
839+
summary: ""
840+
requestBody:
841+
content:
842+
application/json:
843+
schema:
844+
$ref: '#/components/schemas/ExampleService_StreamUserNotifications_Request'
845+
responses:
846+
'200':
847+
description: OK
848+
content:
849+
application/x-ndjson:
850+
schema:
851+
$ref: '#/components/schemas/ExampleService_StreamUserNotifications_Response'
852+
# OpenAPI 3.2.0 streaming (itemSchema) is not supported by 3.1.0 tooling:
853+
# itemSchema:
854+
# $ref: '#/components/schemas/ExampleService_StreamUserNotifications_Response'
855+
'4XX':
856+
description: Client error
857+
content:
858+
application/json:
859+
schema:
860+
oneOf:
861+
- $ref: '#/components/schemas/ErrorWebrpcEndpoint'
862+
- $ref: '#/components/schemas/ErrorWebrpcRequestFailed'
863+
- $ref: '#/components/schemas/ErrorWebrpcBadRoute'
864+
- $ref: '#/components/schemas/ErrorWebrpcBadMethod'
865+
- $ref: '#/components/schemas/ErrorWebrpcBadRequest'
866+
- $ref: '#/components/schemas/ErrorWebrpcClientAborted'
867+
- $ref: '#/components/schemas/ErrorWebrpcStreamLost'
868+
- $ref: '#/components/schemas/ErrorRateLimited'
869+
'5XX':
870+
description: Server error
871+
content:
872+
application/json:
873+
schema:
874+
oneOf:
875+
- $ref: '#/components/schemas/ErrorWebrpcBadResponse'
876+
- $ref: '#/components/schemas/ErrorWebrpcServerPanic'
877+
- $ref: '#/components/schemas/ErrorWebrpcInternalError'
878+
- $ref: '#/components/schemas/ErrorDatabaseDown'
806879
/rpc/AdminService/ListUsers:
807880
post:
808881
operationId: AdminService-ListUsers

‎main.go.tmpl‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@
6969
# Code generated by webrpc-gen@{{.WebrpcGenVersion}} with {{.WebrpcTarget}} generator; DO NOT EDIT
7070
#
7171
# {{.WebrpcGenCommand}}
72-
openapi: 3.2.0
72+
openapi: 3.0.0
7373
info:
7474
title: '{{ get $opts "title" }}'
7575
version: '{{ get $opts "apiVersion" }}'
@@ -167,9 +167,18 @@ paths:
167167
'200':
168168
description: OK
169169
content:
170+
{{- if eq $method.StreamOutput false }}
170171
application/json:
171172
schema:
172173
$ref: '#/components/schemas/{{$service.Name}}_{{$method.Name}}_Response'
174+
{{- else }}
175+
application/x-ndjson:
176+
schema:
177+
$ref: '#/components/schemas/{{$service.Name}}_{{$method.Name}}_Response'
178+
# OpenAPI 3.2.0 streaming (itemSchema) is not supported by 3.1.0 tooling:
179+
# itemSchema:
180+
# $ref: '#/components/schemas/{{$service.Name}}_{{$method.Name}}_Response'
181+
{{- end }}
173182
'4XX':
174183
description: Client error
175184
content:

0 commit comments

Comments
 (0)