Improve summary, description and @deprecated annotations

.github/workflows/ci.yml

@@ -15,7 +15,7 @@ jobs:
       - uses: actions/checkout@v3
       - name: Install webrpc-gen
         run: |
-          curl -o ./webrpc-gen -fLJO https://github.com/webrpc/webrpc/releases/download/v0.20.1/webrpc-gen.linux-amd64
+          curl -o ./webrpc-gen -fLJO https://github.com/webrpc/webrpc/releases/download/v0.25.0/webrpc-gen.linux-amd64
           chmod +x ./webrpc-gen
           echo $PWD >> $GITHUB_PATH
 

_examples/Makefile

@@ -1,6 +1,10 @@
 .PHONY: all generate diff
 
-all: generate diff
+all:
+	@echo "make <cmd>:"
+	@echo ""
+	@echo "commands:"
+	@awk -F'[ :]' '/^#+/ {comment=$$0; gsub(/^#+[ ]*/, "", comment)} !/^(_|all:)/ && /^([A-Za-z_-]+):/ && !seen[$$1]++ {printf "  %-24s %s\n", $$1, (comment ? "- " comment : ""); comment=""} !/^#+/ {comment=""}' Makefile
 
 generate:
 	SECURITY_SCHEMES="{ \
@@ -30,3 +34,7 @@ generate:
 
 diff:
 	git diff --color --ignore-all-space --ignore-blank-lines --exit-code .
+
+swagger:
+	echo "http://localhost:8088"
+	docker run -p 8088:8080 -v $$(pwd):/docs -e SWAGGER_JSON=/docs/openapi.gen.yaml swaggerapi/swagger-ui

_examples/openapi.gen.yaml

@@ -1,6 +1,6 @@
-# example v0.0.1 9e3db8dcce83f00fbc6c12b6a2b712b5fdd38874
+# example v0.0.1 ee5a444237d744dbda91bc77751f0b0d698e7502
 # --
-# Code generated by webrpc-gen@v0.20.1 with ../ generator; DO NOT EDIT
+# Code generated by webrpc-gen@v0.25.0 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.0.0
@@ -411,6 +411,8 @@ components:
           type: string
         email:
           type: string
+    ExampleService_Ping_Request:
+      type: object
     ExampleService_GetUser_Request:
       type: object
       properties:
@@ -442,6 +444,8 @@ components:
       type: object
     ExampleService_GetAllOptional_Request:
       type: object
+    ExampleService_Ping_Response:
+      type: object
     ExampleService_GetUser_Response:
       type: object
       properties:
@@ -483,9 +487,9 @@ components:
       properties:
         optional:
           $ref: '#/components/schemas/Optional'
-    ClonedService_ListUsers_Request:
+    AdminService_ListUsers_Request:
       type: object
-    ClonedService_ListUsers_Response:
+    AdminService_ListUsers_Response:
       type: object
       properties:
         users:
@@ -495,10 +499,52 @@ components:
             $ref: '#/components/schemas/User'
 
 paths:
+  /rpc/ExampleService/Ping:
+    post:
+      summary: "Deprecated."
+      deprecated: true
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ExampleService_Ping_Request'
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ExampleService_Ping_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/ErrorWebrpcClientDisconnected'
+                - $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/ExampleService/GetUser:
     post:
-      summary: GetUser
+      summary: "Deprecated: Use GetUserV2 instead."
       deprecated: true
+      security:
+          - JWT: []
       requestBody:
         content:
           application/json:
@@ -537,10 +583,12 @@ paths:
                 - $ref: '#/components/schemas/ErrorDatabaseDown'
   /rpc/ExampleService/GetUserV2:
     post:
-      summary: GetUserV2
+      summary: "GetUserV2 returns user based on given userID."
       security:
-          - ApiKeyAuth: []
-          - ServiceAuth: []
+          - JWT: []
+      description: |
+
+        Replaces GetUser endpoint.
       requestBody:
         content:
           application/json:
@@ -579,7 +627,12 @@ paths:
                 - $ref: '#/components/schemas/ErrorDatabaseDown'
   /rpc/ExampleService/FindUser:
     post:
-      summary: FindUser
+      summary: "FindUser searches for a user using the given search filter."
+      security:
+          - JWT: []
+      description: |
+
+        The filters are q (string) and active (bool).
       requestBody:
         content:
           application/json:
@@ -618,7 +671,9 @@ paths:
                 - $ref: '#/components/schemas/ErrorDatabaseDown'
   /rpc/ExampleService/ListUsers:
     post:
-      summary: ListUsers
+      summary: "ListUsers returns all users."
+      security:
+          - JWT: []
       requestBody:
         content:
           application/json:
@@ -657,7 +712,7 @@ paths:
                 - $ref: '#/components/schemas/ErrorDatabaseDown'
   /rpc/ExampleService/GetComplex:
     post:
-      summary: GetComplex
+      summary: ""
       requestBody:
         content:
           application/json:
@@ -696,7 +751,7 @@ paths:
                 - $ref: '#/components/schemas/ErrorDatabaseDown'
   /rpc/ExampleService/GetAllOptional:
     post:
-      summary: GetAllOptional
+      summary: ""
       requestBody:
         content:
           application/json:
@@ -733,21 +788,23 @@ paths:
                 - $ref: '#/components/schemas/ErrorWebrpcServerPanic'
                 - $ref: '#/components/schemas/ErrorWebrpcInternalError'
                 - $ref: '#/components/schemas/ErrorDatabaseDown'
-  /rpc/ClonedService/ListUsers:
+  /rpc/AdminService/ListUsers:
     post:
-      summary: ListUsers
+      summary: ""
+      security:
+          - JWT: []
       requestBody:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/ClonedService_ListUsers_Request'
+              $ref: '#/components/schemas/AdminService_ListUsers_Request'
       responses:
         '200':
           description: OK
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClonedService_ListUsers_Response'
+                $ref: '#/components/schemas/AdminService_ListUsers_Response'
         '4XX':
           description: Client error
           content:

_examples/proto.ridl

@@ -41,20 +41,38 @@ struct ComplexType
   - user: User
 
 struct Optional
-    - name?: string
-    - email?: string
+  - name?: string
+  - email?: string
 
 service ExampleService
-  @deprecated:GetUserV2
+  @deprecated
+  - Ping()
+
+  @deprecated:"Use GetUserV2 instead."
+  @auth:JWT
   - GetUser(header: map<string,string>, userID: uint64) => (code: uint32, user: User)
-  @auth:"ApiKeyAuth,ServiceAuth"
+
+  # 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).
+  @auth:JWT
   - FindUser(s: SearchFilter) => (name: string, user: User)
+
+  # ListUsers returns all users.
+  @auth:JWT
   - ListUsers() => (users: []User)
-  - GetComplex() => (complex: ComplexType)
+
+  - GetComplex() => (complex: ComplexType)  
   - GetAllOptional() => (optional: Optional)
 
-service ClonedService
+service AdminService
+  @auth:JWT
   - ListUsers() => (users: []User)
 
 error 100 RateLimited     "too many requests"   HTTP 429

main.go.tmpl

@@ -131,10 +131,11 @@ components:
 paths:
 {{- range $_, $service := .Services -}}
   {{- range $_, $method := .Methods}}
+  {{- $deprecated := index $method.Annotations "deprecated" }}
   /rpc/{{$service.Name}}/{{$method.Name}}:
     post:
-      summary: {{$method.Name}}
-      {{- if (index $method.Annotations "deprecated") }}
+      summary: "{{ if $deprecated }}{{ if $deprecated.Value }}Deprecated: {{$deprecated.Value}}{{else}}Deprecated.{{end}}{{else if gt (len $method.Comments) 0}}{{index $method.Comments 0}}{{end}}"
+      {{- if $deprecated }}
       deprecated: true
       {{- end }}
       {{- if (index $opts "securityAnnotation") }}
@@ -148,9 +149,14 @@ paths:
         {{- end }}
       {{- end }}
       {{- end }}
-      {{- if gt (len $method.Comments) 0 }}
-      description: "{{ replaceAll (join $method.Comments "\n") "\"" "'" }}"
-    {{- end }}
+      {{- if gt (len $method.Comments) 1 }}
+      description: |
+        {{- range $i, $comment := $method.Comments }}
+        {{- if gt $i 0 }}
+        {{$comment}}
+        {{- end }}
+        {{- end }}
+      {{- end }}
       requestBody:
         content:
           application/json: