#utoipa #prost #protobuf #open-api #serialization #compiler-plugin

bin+lib protoc-gen-prost-utoipa

Protocol Buffers compiler plugin providing utoipa schemas

1 unstable release

0.1.0 Apr 6, 2023

#6 in #utoipa

Apache-2.0

12KB
186 lines

protoc-gen-prost-utoipa

A protoc plugin that generates utoipa schema implementations from proto files.

When used in projects that use only Rust code, the preferred mechanism for generating protobuf definitions with Prost! is to use prost-build from within a build.rs file and then generate utoipa schemas using prutoipa-build. However, when working in polyglot environments, it can be advantageous to utilize common tooling in the Protocol Buffers ecosystem. One common tool used for this purpose is buf, which simplifies the code generation process and includes several useful features, including linting, package management, and breaking change detection.

Usage with protoc and protoc-gen-prost

Firstly, ensure that protoc-gen-prost-utoipa has been installed within a directory on your $PATH.

To make it easier to work with the base definitions generated by prost, this plugin assumes that it is being run in a chained mode in the same protoc invocation as protoc-gen-prost. This can be done by specifying multiple plugins in the same protoc invocation like so:

protoc -I proto proto/greeter/v1/greeter.proto \
    --prost_out=proto/gen \
    --prost-utoipa_out=proto/gen

When running as separate invocations, protoc won't be aware of the base definitions that were generated by protoc-gen-prost. In this case, using the no_include directive is necessary, and you will need to separately include the generated .utoipa.rs file.

protoc -I proto proto/greeter/v1/greeter.proto \
    --prost_out=proto/gen \

protoc -I proto proto/greeter/v1/greeter.proto \
    --prost-utoipa_out=proto/gen \
    --prost-utoipa_opt=no_include

Usage with buf

Not yet...

Dependencies

~9–19MB
~269K SLoC