Skip to content

Latest commit

 

History

History
260 lines (239 loc) · 20.9 KB

README.md

File metadata and controls

260 lines (239 loc) · 20.9 KB
Raw

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

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

Authors

License

MIT LICENSE