# protoc-gen-prost-utoipa

A `protoc` plugin that generates _[utoipa]_ schema implementations from proto files.

[utoipa]: https://github.com/juhaku/utoipa

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.

[`prost-build`]: https://docs.rs/prost-build
[`prutoipa-build`]: https://github.com/maarlo/prutoipa/tree/master/prutoipa-build
[buf]: https://buf.build

### 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:

```shell
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.

```shell
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...