Downgrade back to OpenAPI 3.0.0, tooling is not yet ready

README.md

@@ -1,8 +1,8 @@
-# webrpc OpenAPI 3.2.0 (Swagger) generator  <!-- omit in toc -->
+# webrpc OpenAPI 3.0.0 (Swagger) generator  <!-- omit in toc -->
 
 This repo contains the templates used by the [webrpc-gen](https://github.com/webrpc/webrpc) cli to code-generate OpenAPI documentation from webrpc schema.
 
-- [Generate OpenAPI 3.2.0 YAML file](#generate-openapi-320-yaml-file)
+- [Generate OpenAPI 3.0.0 YAML file](#generate-openapi-300-yaml-file)
   - [Set custom template variables](#set-custom-template-variables)
 - [Open in Swagger UI](#open-in-swagger-ui)
 - [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
 - [Authors](#authors)
 - [License](#license)
 
-# Generate OpenAPI 3.2.0 YAML file
+# Generate OpenAPI 3.0.0 YAML file
 ```bash
 webrpc-gen -schema=./proto.ridl -target=openapi -out petstore.gen.yaml
 ```

_examples/Makefile

@@ -22,7 +22,7 @@ generate:
               } \
             }"; \
 	webrpc-gen \
-		-schema=./proto.ridl \
+		-schema=./api.ridl \
 		-target=../ \
 		-out=./openapi.gen.yaml \
 		-title="Example webrpc API" \
@@ -37,4 +37,4 @@ diff:
 
 swagger:
 	@echo "Swagger UI is available at http://localhost:8088"
-	docker run -p 8088:8080 -v $$(pwd):/docs -e SWAGGER_JSON=/docs/openapi.gen.yaml swaggerapi/swagger-ui
+	docker run -p 8088:8080 -v $$(pwd):/docs -e SWAGGER_JSON=/docs/openapi.gen.yaml swaggerapi/swagger-ui:v5.31.0

_examples/proto.ridl → _examples/api.ridl

@@ -3,6 +3,44 @@ webrpc = v1 # version of webrpc schema format (ridl or json)
 name = example # name of your backend app
 version = v0.0.1 # version of your schema
 
+service ExampleService
+    @deprecated
+  - Ping()
+
+    @deprecated:"Use GetUserV2 instead."
+    @auth:JWT
+  - GetUser(header: map<string,string>, userID: uint64) => (code: uint32, user: User)
+
+    # GetUserV2 returns user based on given userID.
+    # Replaces GetUser endpoint.
+    @auth:JWT
+  - GetUserV2(header: map<string,string>, userID: uint64) => (code: uint32, user: User, profilePicture: string)
+
+    # FindUser searches for a user using the given search filter.
+    #
+    # The filters are q (string) and active (bool).
+    #
+    # The minimal length of the "q" filter is 3 characters.
+    @auth:JWT
+  - FindUser(s: SearchFilter) => (name: string, user: User)
+
+    # ListUsers returns all users.
+    @auth:JWT
+  - ListUsers() => (users: []User)
+
+  - GetComplex() => (complex: ComplexType)
+  - GetAllOptional() => (optional: Optional)
+
+  - StreamUserNotifications(StreamNotificationsRequest) => stream (StreamNotificationsResponse)
+
+service AdminService
+    @auth:JWT
+  - ListUsers() => (users: []User)
+
+error 100 RateLimited  "too many requests" HTTP 429
+error 101 DatabaseDown "service outage"    HTTP 503
+
+
 enum Kind: uint32
   - USER
   - ADMIN
@@ -44,38 +82,11 @@ struct Optional
   - name?: string
   - email?: string
 
-service ExampleService
-    @deprecated
-  - Ping()
-
-    @deprecated:"Use GetUserV2 instead."
-    @auth:JWT
-  - GetUser(header: map<string,string>, userID: uint64) => (code: uint32, user: User)
-
-    # GetUserV2 returns user based on given userID.
-    # Replaces GetUser endpoint.
-    @auth:JWT
-  - GetUserV2(header: map<string,string>, userID: uint64) => (code: uint32, user: User, profilePicture: string)
+struct StreamNotificationsRequest
 
-    # FindUser searches for a user using the given search filter.
-    #
-    # The filters are q (string) and active (bool).
-    #
-    # The minimal length of the "q" filter is 3 characters.
-    @auth:JWT
-  - FindUser(s: SearchFilter) => (name: string, user: User)
-
-    # ListUsers returns all users.
-    @auth:JWT
-  - ListUsers() => (users: []User)
-
-  - GetComplex() => (complex: ComplexType)
-  - GetAllOptional() => (optional: Optional)
-
-service AdminService
-    @auth:JWT
-  - ListUsers() => (users: []User)
-
-error 100 RateLimited  "too many requests" HTTP 429
-error 101 DatabaseDown "service outage"    HTTP 503
+struct StreamNotificationsResponse
+  - notification: Notification
 
+struct Notification
+  - message: string
+  - timestamp: timestamp

_examples/openapi.gen.yaml

@@ -1,9 +1,9 @@
-# example v0.0.1 9814b024890e4f9bf0fb6406686c29bcc402b24a
+# example v0.0.1 55eeccc8db95e08d65f0da63acfdcbd92cc1e6fa
 # --
 # Code generated by [email protected] with ../ generator; DO NOT EDIT
 # 
-# 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'               }             }
-openapi: 3.2.0
+# 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'               }             }
+openapi: 3.0.0
 info:
   title: 'Example webrpc API'
   version: 'v22.11.8'
@@ -411,6 +411,25 @@ components:
           type: string
         email:
           type: string
+    StreamNotificationsRequest:
+      type: object
+    StreamNotificationsResponse:
+      type: object
+      required:
+        - notification
+      properties:
+        notification:
+          $ref: '#/components/schemas/Notification'
+    Notification:
+      type: object
+      required:
+        - message
+        - timestamp
+      properties:
+        message:
+          type: string
+        timestamp:
+          type: string
     ExampleService_Ping_Request:
       type: object
     ExampleService_GetUser_Request:
@@ -444,6 +463,11 @@ components:
       type: object
     ExampleService_GetAllOptional_Request:
       type: object
+    ExampleService_StreamUserNotifications_Request:
+      type: object
+      properties:
+        streamNotificationsRequest:
+          $ref: '#/components/schemas/StreamNotificationsRequest'
     ExampleService_Ping_Response:
       type: object
     ExampleService_GetUser_Response:
@@ -487,6 +511,11 @@ components:
       properties:
         optional:
           $ref: '#/components/schemas/Optional'
+    ExampleService_StreamUserNotifications_Response:
+      type: object
+      properties:
+        streamNotificationsResponse:
+          $ref: '#/components/schemas/StreamNotificationsResponse'
     AdminService_ListUsers_Request:
       type: object
     AdminService_ListUsers_Response:
@@ -803,6 +832,50 @@ paths:
                 - $ref: '#/components/schemas/ErrorWebrpcServerPanic'
                 - $ref: '#/components/schemas/ErrorWebrpcInternalError'
                 - $ref: '#/components/schemas/ErrorDatabaseDown'
+  /rpc/ExampleService/StreamUserNotifications:
+    post:
+      operationId: ExampleService-StreamUserNotifications
+      tags: ["ExampleService"]
+      summary: ""
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ExampleService_StreamUserNotifications_Request'
+      responses:
+        '200':
+          description: OK
+          content:
+            application/x-ndjson:
+              schema:
+                $ref: '#/components/schemas/ExampleService_StreamUserNotifications_Response'
+              # OpenAPI 3.2.0 streaming (itemSchema) is not supported by 3.1.0 tooling:
+              # itemSchema:
+              #   $ref: '#/components/schemas/ExampleService_StreamUserNotifications_Response'
+        '4XX':
+          description: Client error
+          content:
+            application/json:
+              schema:
+                oneOf:
+                - $ref: '#/components/schemas/ErrorWebrpcEndpoint'
+                - $ref: '#/components/schemas/ErrorWebrpcRequestFailed'
+                - $ref: '#/components/schemas/ErrorWebrpcBadRoute'
+                - $ref: '#/components/schemas/ErrorWebrpcBadMethod'
+                - $ref: '#/components/schemas/ErrorWebrpcBadRequest'
+                - $ref: '#/components/schemas/ErrorWebrpcClientAborted'
+                - $ref: '#/components/schemas/ErrorWebrpcStreamLost'
+                - $ref: '#/components/schemas/ErrorRateLimited'
+        '5XX':
+          description: Server error
+          content:
+            application/json:
+              schema:
+                oneOf:
+                - $ref: '#/components/schemas/ErrorWebrpcBadResponse'
+                - $ref: '#/components/schemas/ErrorWebrpcServerPanic'
+                - $ref: '#/components/schemas/ErrorWebrpcInternalError'
+                - $ref: '#/components/schemas/ErrorDatabaseDown'
   /rpc/AdminService/ListUsers:
     post:
       operationId: AdminService-ListUsers

main.go.tmpl

@@ -69,7 +69,7 @@
 # Code generated by webrpc-gen@{{.WebrpcGenVersion}} with {{.WebrpcTarget}} generator; DO NOT EDIT
 # 
 # {{.WebrpcGenCommand}}
-openapi: 3.2.0
+openapi: 3.0.0
 info:
   title: '{{ get $opts "title" }}'
   version: '{{ get $opts "apiVersion" }}'
@@ -167,9 +167,18 @@ paths:
         '200':
           description: OK
           content:
+            {{- if eq $method.StreamOutput false }}
             application/json:
               schema:
                 $ref: '#/components/schemas/{{$service.Name}}_{{$method.Name}}_Response'
+            {{- else }}
+            application/x-ndjson:
+              schema:
+                $ref: '#/components/schemas/{{$service.Name}}_{{$method.Name}}_Response'
+              # OpenAPI 3.2.0 streaming (itemSchema) is not supported by 3.1.0 tooling:
+              # itemSchema:
+              #   $ref: '#/components/schemas/{{$service.Name}}_{{$method.Name}}_Response'
+            {{- end }}
         '4XX':
           description: Client error
           content: