diff --git a/README.md b/README.md index 842ef63..e45edb9 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ -# webrpc OpenAPI 3.2.0 (Swagger) generator +# webrpc OpenAPI 3.0.0 (Swagger) generator 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 ``` diff --git a/_examples/Makefile b/_examples/Makefile index f24c475..787faec 100644 --- a/_examples/Makefile +++ b/_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 diff --git a/_examples/proto.ridl b/_examples/api.ridl similarity index 87% rename from _examples/proto.ridl rename to _examples/api.ridl index cfa34b8..1bc8c6d 100644 --- a/_examples/proto.ridl +++ b/_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, userID: uint64) => (code: uint32, user: User) + + # 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). + # + # 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, userID: uint64) => (code: uint32, user: User) - - # GetUserV2 returns user based on given userID. - # Replaces GetUser endpoint. - @auth:JWT - - GetUserV2(header: map, 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 diff --git a/_examples/openapi.gen.yaml b/_examples/openapi.gen.yaml index ad53d34..f6e9892 100644 --- a/_examples/openapi.gen.yaml +++ b/_examples/openapi.gen.yaml @@ -1,9 +1,9 @@ -# example v0.0.1 9814b024890e4f9bf0fb6406686c29bcc402b24a +# example v0.0.1 55eeccc8db95e08d65f0da63acfdcbd92cc1e6fa # -- # Code generated by webrpc-gen@v0.31.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.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 diff --git a/main.go.tmpl b/main.go.tmpl index ae04946..a3ff199 100644 --- a/main.go.tmpl +++ b/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: