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

Example:

server url and server description will become part of the servers format in the end to keeep 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/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

Name		Name	Last commit message	Last commit date
Latest commit History 58 Commits
.github/workflows		.github/workflows
_examples		_examples
LICENSE		LICENSE
README.md		README.md
embed.go		embed.go
errorType.go.tmpl		errorType.go.tmpl
fieldType.go.tmpl		fieldType.go.tmpl
go.mod		go.mod
help.go.tmpl		help.go.tmpl
main.go.tmpl		main.go.tmpl
type.go.tmpl		type.go.tmpl

License

webrpc/gen-openapi

Folders and files

Latest commit

History

Repository files navigation

webrpc OpenAPI 3.x (Swagger) generator

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

About

Topics

Resources

License

Stars

Watchers

Forks

Languages