How to generate API reference from .proto?

[keisku]

I would like to generate API reference from .proto files by using buf like https://github.com/pseudomuto/protoc-gen-doc.
Are there ways to do it?

[johanbrandhorst]

Hi, thanks for your issue! Yes, you can use this plugin with buf! If you want to get an introduction to using buf (including how to generate code using plugins like protoc-gen-doc), I would recommend going through the tour in our docs: https://docs.buf.build/tour/introduction.

If you're already a bit familiar with buf, what you'll need to do to use protoc-gen-doc largely comes down to:

1. Install the plugin locally. The installation instructions given by the author suggest installing via the Go tool:

   $ go install github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc
   

   Running this command will download and compile the plugin for your local system and put it in GOPATH/bin/protoc-gen-doc. You'll need to ensure this path is available on your $PATH for the next step, so you may want to run something like:

   $ export PATH=$PATH:(go env GOPATH)/bin
   

2. Define a buf.gen.yaml. For your use case, it shouldn't have to be more complicated than this:

   version: v1
   plugins:
     - name: doc # buf will look for this protoc-gen-doc on the $PATH
       # path: /path/to/protoc-gen-doc # Optionally, instead of updating your $PATH in the previous step, you can specify the path to the binary explicitly here.
       out: ./gen/doc

3. Run buf generate providing your sources as the input. It defaults to the current directory, so if you have an existing protobuf module, you can simply run

   $ buf generate
   

   from the root of your module.

EDIT: change name: protoc-gen-doc to name: doc as suggested by @amckinney.

[bufdev]

Another option is to use the Buf Schema Registry's built-in documentation generator by the way! https://docs.buf.build/bsr/documentation

[keisku]

@johanbrandhorst

Thank you!

I am trying as following your instruction but, I've got the error message even though protoc-gen-doc exists under ~/go/bin.

Failure: plugin protoc-gen-doc: could not find protoc plugin for name protoc-gen-doc

I've also executed buf mod update.

My buf.gen.yaml is like this.

version: v1
plugins:
  - name: go
    out: .
    opt: paths=source_relative
  - name: go-grpc
    out: .
    opt:
      - paths=source_relative
      - require_unimplemented_servers=false
  - name: grpc-gateway
    out: .
    opt: paths=source_relative
  - name: protoc-gen-doc
    out: .

And buf.yaml here.

version: v1
deps:
  - buf.build/googleapis/googleapis
lint:
  use:
    - DEFAULT
  except:
    - PACKAGE_DIRECTORY_MATCH
breaking:
  use:
    - FILE

Do you have any ideas?

[johanbrandhorst]

What does which protoc-gen-doc show? If it shows nothing, you may have missed the step about setting your PATH:

export PATH=$PATH:(go env GOPATH)/bin

If you need more help, can you reach out on our Slack? https://buf.build/links/slack. This issue tracker isn't great for quick troubleshooting.

[keisku]

oh, I should've provided it, too.

This is exactly same as $GOPATH/bin/protoc-gen-doc.

which protoc-gen-doc
/Users/keisukeumegaki/go/bin/protoc-gen-doc

Besides, I've joined the Slack channel.

[amckinney]

Replied in Slack, but including here for posterity - your buf.gen.yaml should reference doc (not the protoc-gen- prefix).

version: v1
plugins:
  - name: go
    out: .
    opt: paths=source_relative
  - name: go-grpc
    out: .
    opt:
      - paths=source_relative
      - require_unimplemented_servers=false
  - name: grpc-gateway
    out: .
    opt: paths=source_relative
  - name: doc
    out: .

[keisku]

It works! Thanks:pray:

[houseofmercy-github]

I had some trouble getting the source_relative setting right with the protoc-gen-doc plugin.
For the benefit of anyone else who finds there way here this is what worked for me:

version: v1
plugins:
  - name: doc
    out: ./gen/doc
    opt: html,index.html,source_relative