From 41477305f77b22333e78754ebbb8301cc3eebdd5 Mon Sep 17 00:00:00 2001 From: Vojtech Vitek Date: Tue, 25 Mar 2025 22:41:46 +0100 Subject: [PATCH 1/3] Improve summary, description and @deprecated annotations --- main.go.tmpl | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/main.go.tmpl b/main.go.tmpl index 1c30992..b359cfa 100644 --- a/main.go.tmpl +++ b/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: From db5552fd69c0e371cfaca1b7965ead18f7a4a522 Mon Sep 17 00:00:00 2001 From: Vojtech Vitek Date: Tue, 25 Mar 2025 22:43:38 +0100 Subject: [PATCH 2/3] Improve example and regenerate --- _examples/Makefile | 10 ++++- _examples/openapi.gen.yaml | 89 +++++++++++++++++++++++++++++++------- _examples/proto.ridl | 30 ++++++++++--- 3 files changed, 106 insertions(+), 23 deletions(-) diff --git a/_examples/Makefile b/_examples/Makefile index d3857ee..2ea37e5 100644 --- a/_examples/Makefile +++ b/_examples/Makefile @@ -1,6 +1,10 @@ .PHONY: all generate diff -all: generate diff +all: + @echo "make :" + @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 diff --git a/_examples/openapi.gen.yaml b/_examples/openapi.gen.yaml index b47b6f9..20599bc 100644 --- a/_examples/openapi.gen.yaml +++ b/_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: diff --git a/_examples/proto.ridl b/_examples/proto.ridl index e07bcab..bf30b9d 100644 --- a/_examples/proto.ridl +++ b/_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, userID: uint64) => (code: uint32, user: User) - @auth:"ApiKeyAuth,ServiceAuth" + + # GetUserV2 returns user based on given userID. + # + # Replaces GetUser endpoint. + @auth:JWT - GetUserV2(header: map, 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 From 2276e40e228a58d8b8ecc19fd25d4c3cf29e552b Mon Sep 17 00:00:00 2001 From: Vojtech Vitek Date: Tue, 25 Mar 2025 22:46:01 +0100 Subject: [PATCH 3/3] Update webrpc-gen to v0.25.0 --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2d8b679..9162066 100644 --- a/.github/workflows/ci.yml +++ b/.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