webrpc OpenAPI 3.x (Swagger) generator

This repo contains the templates used by the webrpc-gen cli to code-generate OpenAPI documentation from webrpc schema.

• Generate OpenAPI 3.x YAML file
  • Set custom template variables
• Open in Swagger UI
• Build static HTML documentation with Redocly
• Generate client/docs via OpenAPI generator
  • Generate C# client for .NET 6.0
  • List of OpenAPI generators (as of Jan 5 2023)
• Authors
• License

Generate OpenAPI 3.x YAML file

webrpc-gen -schema=./proto.ridl -target=openapi -out petstore.gen.yaml

or

webrpc-gen -schema=./proto.ridl -target=github.com/webrpc/[email protected] -out petstore.gen.yaml

Set custom template variables

Change any of the following default values by passing -option="Value" CLI flag to webrpc-gen.

webrpc-gen -option	Default value	Example value
-title	{Services[0].Name} API	"Example API"
-apiVersion	""	v22.10.25
-serverUrl	""	https://api.example.com
-serverDescription	""	"Staging API"
-servers	""	http://localhost:8080;description,http://localhost:8081;description
-securityAnnotation	""	@auth
-securitySchemes	""	{"ApiKeyAuth":{"type":"apiKey", "in":"header", "description":"Access key for authenticating requests", "name":"X-Access-Key"}}

Example:

• server url and server description will become part of the servers format in the end to keep it backward compatible
• means that the result will be server="http://localhost:8080;description,http://localhost:8081;description,https://api.example.com;Production"

webrpc-gen \ 
  -schema=./petstore.ridl \ 
  -target=github.com/webrpc/[email protected] \ 
  -out petstore.gen.yaml \ 
  -title="Example webrpc API" \ 
  -apiVersion="v22.11.8" \ 
  -serverUrl=https://api.example.com \ 
  -serverDescription="Production"
  -servers="http://localhost:8080;description,http://localhost:8081;description"

• securityAnnotation must match the custom annotation you are using in your project to describe ACL for specific service methods
• securitySchemes give you possibility to pass an openapi security schemes which are later matched by your custom acl annotation. In this example it's an @auth annotation. Example with security annotation:

// proto.ridl
service ExampleService
  @auth:"ApiKeyAuth,ServiceAuth"
  - GetUserV2(header: map<string,string>, userID: uint64) => (profilePicture: string)

// Makefile
SECURITY_SCHEMES="{ \
  'ApiKeyAuth': { \
    'type': 'apiKey', \
    'in': 'header', \
    'description': 'Project access key for authenticating requests', \
    'name': 'X-Access-Key' \
  }, \
}"; \
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="$$SECURITY_SCHEMES"

Open in Swagger UI

Open generated documentation in Swagger editor:

docker run -p 8088:8080 -v $(pwd):/app -e SWAGGER_JSON=/app/petstore.gen.yaml swaggerapi/swagger-ui

Or in Swagger editor:

docker run -p 8088:8080 -v $(pwd):/app -e SWAGGER_FILE=/app/petstore.gen.yaml swaggerapi/swagger-editor

And go to http://localhost:8088

Build static HTML documentation with Redocly

You can use Redocly tool to build static HTML documentation. Customize the look and feel through theming options.

Example:

docker run --rm -v $(pwd):/app -w /app ghcr.io/redocly/redoc/cli build petstore.gen.yaml

Generate client/docs via OpenAPI generator

You can use OpenAPI generator to generate API clients in different languages or documentation from the generated OpenAPI yaml file.

Generate C# client for .NET 6.0

docker run --rm -v "${PWD}:/app" openapitools/openapi-generator-cli:v6.2.1 generate -i /app/openapi.gen.yaml -g csharp-netcore -p targetFramework=net6.0 -o /app/csharp-net-7.0

List of OpenAPI generators (as of Jan 5 2023)

• ada
• ada-server
• android
• apache2
• apex
• asciidoc
• aspnetcore
• avro-schema
• bash
• crystal
• c
• clojure
• cwiki
• cpp-qt-client
• cpp-qt-qhttpengine-server
• cpp-pistache-server
• cpp-restbed-server
• cpp-restbed-server-deprecated
• cpp-restsdk
• cpp-tiny
• cpp-tizen
• cpp-ue4
• csharp
• csharp-netcore
• csharp-dotnet2
• csharp-netcore-functions
• dart
• dart-dio
• eiffel
• elixir
• elm
• erlang-client
• erlang-proper
• erlang-server
• fsharp-functions
• fsharp-giraffe-server
• go
• go-echo-server
• go-server
• go-gin-server
• graphql-schema
• graphql-nodejs-express-server
• groovy
• kotlin
• kotlin-server
• kotlin-spring
• kotlin-vertx
• ktorm-schema
• haskell-http-client
• haskell
• haskell-yesod
• java
• jaxrs-cxf-client
• java-helidon-client
• java-helidon-server
• java-inflector
• java-micronaut-client
• java-micronaut-server
• java-msf4j
• java-pkmst
• java-play-framework
• java-undertow-server
• java-vertx
• java-vertx-web
• java-camel
• jaxrs-cxf
• jaxrs-cxf-extended
• jaxrs-cxf-cdi
• jaxrs-jersey
• jaxrs-resteasy
• jaxrs-resteasy-eap
• jaxrs-spec
• javascript
• javascript-apollo-deprecated
• javascript-flowtyped
• javascript-closure-angular
• jmeter
• k6
• lua
• markdown
• mysql-schema
• nim
• nodejs-express-server
• objc
• ocaml
• openapi
• openapi-yaml
• plantuml
• perl
• php
• php-laravel
• php-lumen
• php-slim-deprecated
• php-slim4
• php-symfony
• php-mezzio-ph
• php-dt
• powershell
• protobuf-schema
• python-legacy
• python
• python-fastapi
• python-prior
• python-flask
• python-aiohttp
• python-blueplanet
• r
• ruby
• ruby-on-rails
• ruby-sinatra
• rust
• rust-server
• scalatra
• scala-akka
• scala-akka-http-server
• scala-finch
• scala-httpclient-deprecated
• scala-gatling
• scala-lagom-server
• scala-play-server
• scala-sttp
• scalaz
• spring
• dynamic-html
• html
• html2
• swift5
• typescript
• typescript-angular
• typescript-aurelia
• typescript-axios
• typescript-fetch
• typescript-inversify
• typescript-jquery
• typescript-nestjs
• typescript-node
• typescript-redux-query
• typescript-rxjs
• wsdl-schema

Authors

• golang.cz
• Vojtech Vitek

License

MIT LICENSE