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
-securityAnnotation""@auth
-securitySchemes""{"ApiKeyAuth":{"type":"apiKey", "in":"header", "description":"Access key for authenticating requests", "name":"X-Access-Key"}}

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"

// 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)

Authors

License

MIT LICENSE