Home

Awesome

webrpc OpenAPI 3.x (Swagger) generator <!-- omit in toc -->

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

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

or

webrpc-gen -schema=./proto.ridl -target=github.com/webrpc/gen-openapi@v0.7.0 -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 -optionDefault valueExample 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

Example:

webrpc-gen \ 
  -schema=./petstore.ridl \ 
  -target=github.com/webrpc/gen-openapi@v0.7.0 \ 
  -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"

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)

Authors

License

MIT LICENSE