github.com/cuberat/protoc-gen-docjson@v1.1.1-0.20230510142946-907a0bd92b78/README.md (about) 1 # protoc-gen-docjson 2 3 [](https://github.com/cuberat/protoc-gen-docjson/actions/workflows/unit_tests_main.yml)[](https://github.com/cuberat/protoc-gen-docjson/actions/workflows/unit_tests_dev.yml) 4 5 A protobuf compiler plugin that generates data to use in rendering documentation templates from protobuf specs. 6 7 This plugin generates a JSON file containing meta data from protobuf specifications that is useful for building (in an automated fashion) documentation in HTML, Markdown, etc., for easier reading and distribution. This allows using the comments in the protobuf specifications as documentation in other formats without duplication of effort. In turn, this helps to keep documentation up to date, since the text for the documentation is in the protobuf specifications themselves. 8 9 ## Installation 10 11 Using `protoc-gen-docjson` requires the protobuf compiler (`protoc`) to be installed. It is what calls `protoc-gen-docjson` with the required information about the protobuf files. In turn, the `protoc-gen-docjson` executable must be in your execution path, or, alternatively, provide `protoc` the full path to the executable (using the `--plugin` parameter). 12 13 env GOBIN=/my/bin/dir go install github.com/cuberat/protoc-gen-docjson/cmd/protoc-gen-docjson@latest 14 15 ## Running 16 17 The following command will generate a file named `docs.json` in the `${OUT_DIR}` directory. 18 19 ```sh 20 cd ${proto_dir} && protoc -I${proto_dir} \ 21 --docjson_out="${OUT_DIR}" \ 22 --docjson_opt=outfile=docs.json \ 23 file1 file2 file3 24 ``` 25 26 It is important to `cd` to the directory containing the protobuf specifications if you need to document custom options (extensions to the various `*Options` messages defined in the descriptor protobuf), as the plugin needs to be able to open the files itself in that case. Alternatively, you may provide the protobuf directory path to the plugin by adding the `proto=` parameter to the `--docjson_opt` parameter (separate parameters to `--docjson_opt` with commas). E.g., 27 28 ```sh 29 cd ${proto_dir} && protoc -I${PROTO_DIR} \ 30 --docjson_out="${OUT_DIR}" \ 31 --docjson_opt=outfile=docs.json,proto="${PROTO_DIR}" \ 32 file1 file2 file3 33 ``` 34 35 ### Options 36 37 #### outfile 38 39 Specifies the output file name. The file will be output to the output directory specified by the `docjson_out` parameter provided to the protobuf compiler. 40 41 #### proto 42 43 Specifies the full path to the top-level directory containing the protobuf specifications. 44 45 #### pretty 46 47 Include indentation and other whitespace in the JSON output to make it more human-readable. 48 49 ## Output Structure 50 51 ### Top-Level Fields 52 53 #### `file_name_list` 54 55 A list of the file names provided to the protobuf compiler. The file names are ordered such that files are listed before other files that include them. The file names are actually relative paths. E.g., if you have a subdirectory in your protobuf specification directory, files in the that directory will be prefixed with the directory name. 56 57 #### `file_map` 58 59 A map of file names to [file descriptors](#file-descriptor). 60 61 #### `service_name_list` 62 63 A list of fully-qualified service names appearing in the input files. 64 65 #### `service_map` 66 67 A map of fully-qualified service names to [service descriptors](#service-descriptor). 68 69 #### `message_name_list` 70 71 A list of fully-qualified message names. 72 73 #### `message_map` 74 75 A map of fully-qualified message names to [message descriptors](#message-descriptor). 76 77 #### `extension_name_list` 78 79 A list of fully-qualified extension names. 80 81 #### `extension_map` 82 83 A map of fully-qualified extension names to [extension descriptors](#extension-descriptor) 84 85 #### `enum_name_list` 86 87 A list of fully-qualified enumerations. 88 89 #### `enum_map` 90 91 A map of fully-qualfied enumerations to [enumeration descriptors](#enum-descriptor) 92 93 #### `message_deps` 94 95 A map of fully-qualified message names to a list of the messages and enumerations they depend on. 96 97 #### `service_deps` 98 99 A map of fully-qualified service names to a list of the messages and enumerations they depend on. 100 101 #### `service_file_deps` 102 103 A map of fully-qualified service names to a list of the files containing messages and enumerations they depend on. 104 105 ### Common Fields 106 107 The descriptors describe below have some fields in common, so those are described here. 108 109 #### Comments 110 111 ##### `description` 112 113 This is a description generated from the `leading_comments` and `trailing_comments` fields. If both the `leading_comments` and `trailing_comments` fields are non-empty, the description is generated by appending a space to the content of `leading_comments` and then appending the content of `trailing_comments`. Otherwise, the content of whichever fields is populated will be used as the description. 114 115 ##### `leading_comments` 116 117 Leading comments appear before, but are attached to, an item in the protobuf specification. The following is an example of a leading comment: 118 119 ```protobuf 120 // Leading comment for the name field. 121 string name = 1; 122 ``` 123 124 This is not a leading comment, because it is not attached (there is a blank line between the comment and the field specification): 125 126 ```protobuf 127 // NOT a leading comment for the name field. 128 129 string name = 1; 130 ``` 131 132 ##### `trailing_comments` 133 134 Trailing comments appear to the right of an item in the protobuf specification. The following is an example of a trailing comment: 135 136 ```protobuf 137 int32 bar = 3; // Trailing comment for the bar field. 138 ``` 139 140 ##### `leading_detatched_comments` 141 142 This field contains a list of leading detached comments. That is, these are comments appearing between the item in question and the item above it, but they are not attached to the item. In the following example, the block comment is a leading detached comment: 143 144 ```protobuf 145 /* 146 * Leading detached comment for the syntax statement. 147 * A second line. 148 */ 149 150 // This is the syntax statement leading comment. 151 syntax = "proto3"; // This is a trailing comment for syntax. 152 ``` 153 154 Both protobuf specification comment styles are supported here and throughout the specifications: 155 156 ```protobuf 157 // Syntax leading comment for a proto file in a subdirectory. Both block-style 158 // comments and line-style comments work throughout the specifications. 159 160 // This is a syntax statement leading comment. 161 syntax = "proto3"; 162 ``` 163 164 #### `custom_options` 165 166 `custom_options` is a map of fully-qualified names of extensions that extend protobuf descriptor options. For example, if a `method_not_implemented` extension is defined like so: 167 168 ```protobuf 169 extend google.protobuf.MethodOptions { 170 optional bool method_not_implemented = 51235; 171 } 172 ``` 173 174 and the package is specified as `MyServices.Tester`, and a service method is defined like so: 175 176 ```protobuf 177 rpc RunTestV2(MyServices.Tester.TesterRequest) 178 returns (MyServices.Tester.TesterResponse) { 179 option (MyServices.Tester.method_not_implemented) = true; 180 } 181 ``` 182 183 then the `custom_options` field will look like the following: 184 185 ```json 186 "custom_options": { 187 "method_not_implemented": true 188 } 189 ``` 190 191 This gives you more information to use when rendering templates, e.g., highlight the fact that this service method is not ready to use yet. You can find more details on custom options on the [protobuf.dev](https://protobuf.dev/programming-guides/proto/#customoptions) website. 192 193 ### Descriptors 194 195 #### File Descriptor 196 197 Fields: 198 199 * `name`: relative path to the file. 200 * `package`: package name specified by the `package` declaration. 201 * `messages`: a list of messages. See the [Message Descriptor](#message-descriptor) section for details. 202 * `enums`: a list of enumerations. See the [Enum Descriptor](#enum-descriptor) section for details. 203 * `services`: a list of services. See the [Service Descriptor](#service-descriptor) section for details. 204 * `dependencies`: a list of files this file depends on (imports) that are in the list of files provided to the protobuf compiler. 205 * `external_dependencies`: a list of files this file depends on (imports) that are not in the list of files provided to the protobuf compiler. 206 * `options`: a map of options specific to files. See the [File Options](#file-options) section for details. 207 * `extensions`: a list of extensions defined in this file. 208 * `syntax`: a [syntax descriptor](#syntax-declaration). 209 * `custom_options`: a map of custom options. See the [custom_options](#custom_options) section for details. 210 * `declared_custom_options`: if an extension was defined to extend one of the structures used to represent protobuf specifications (e.g., `google.protobuf.MessageOptions`), information on that extension (same information as in the `extensions` field) is provided here as a map of type to list of extensions. The valid types are `file`, `service`, `message`, `field`, `enum_decl`, and `enum_val`. 211 * [Comment fields](#comments) 212 213 #### Syntax Declaration 214 215 * `version`: protobuf syntax version. E.g., "proto2", "proto3". 216 * [Comment fields](#comments) 217 218 ##### File Options 219 220 See the `FileOptions` message in [descriptor.proto](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/descriptor.proto) for official documentation on these options. 221 222 * `java_package` 223 * `java_outer_classname` 224 * `java_multiple_files` 225 * `java_string_check_utf8` 226 * `go_package` 227 * `deprecated` 228 * `cc_enable_arenas` 229 * `objc_class_prefix` 230 * `csharp_namespace` 231 * `swift_prefix` 232 * `php_class_prefix` 233 * `php_namespace` 234 * `php_metadata_namespace` 235 * `ruby_package` 236 237 #### Service Descriptor 238 239 * `name`: name of the service. 240 * `full_name`: fully-qualified name of the service. 241 * `methods`: list of [method descriptors](#method-descriptor). 242 * `options`: a [service options descriptor](#service-options). 243 * `custom_options`: map of [custom options](#custom_options). 244 * [Comment fields](#comments) 245 246 ##### Service Options 247 248 See the `ServiceOptions` message in [descriptor.proto](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/descriptor.proto) for official documentation on this option. 249 250 * `deprecated` 251 252 #### Method Descriptor 253 254 * `name`: name of the method. 255 * `full_name`: full-qualified name of the method. 256 * `request_type`: message name indicating the type in the request. 257 * `request_full_type`: fully-qualified message name indicating the type in the request. 258 * `request_streaming`: boolean indicating whether this method supports client streaming. 259 * `response_type`: message name indicating the type in the response. 260 * `response_full_type` full-qualified message name indicating the type in the response. 261 * `response_streaming`: boolean indicating whether this method supports server streaming. 262 * `options`: a [method options descriptor](#method-options). 263 * `custom_options`: map of [custom options](#custom_options). 264 * [Comment fields](#comments) 265 266 #### Method Options 267 268 See the `MethodOptions` message in [descriptor.proto](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/descriptor.proto) for official documentation on this option. 269 270 * `deprecated` 271 272 #### Message Descriptor 273 274 * `name`: message name. 275 * `full_name`: fully-qualified message name. 276 * `fields`: a list of [field descriptors](#field-descriptor). 277 * `nested_messages`: a list of nested messages. Each message is another Message Descriptor, which can, in turn, have nested messages. 278 * `enums`: list of [enum descriptors](#enum-descriptor). 279 * `oneof_decl`: a list of [oneof descriptors](#oneof-descriptor). 280 * `options`: a [message options descriptor](#message-options). 281 * `custom_options`: map of [custom options](#custom_options). 282 * [Comment fields](#comments) 283 284 ##### Message Options 285 286 See the `MessageOptions` message in [descriptor.proto](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/descriptor.proto) for official documentation on these options. 287 288 * `deprecated` 289 * `map_entry` 290 291 #### Field Descriptor 292 293 * `name`: name of the field. 294 * `full_name`: fully-qualified name of the field. 295 * `type`: type of the field, as a string. E.g., "bool". 296 * `full_type`: fully-qualified type of the field. This differs from `type` when it is a message or enum. 297 * `kind`: similar to `type`, except if the field type is a message or enum, the value will be "message" or "enum". 298 * `label`: the label in the field declaration. E.g., "repeated", "optional". 299 * `field_number`: the field number/slot number of this field. 300 * `default_value`: default value for the field. 301 * `oneof_index`: index representing which `oneof` in the message this field is in. Check `in_oneof` to distinguish between an unset value for `oneof_index` (in which case, the field is not in a oneof, but this field still exists with the value zero) and an actual index. 302 * `in_oneof`: boolean indicating whether this field is declared inside a oneof. 303 * `oneof_name`: name of the `oneof` this field is declared in. 304 * `oneof_full_name`: fully-qualified `oneof` this field is declared in. 305 * `options`: a [field options descriptor](#field-options). 306 * `custom_options`: map of [custom options](#custom_options). 307 * [Comment fields](#comments) 308 309 #### Field Options 310 311 See the `FieldOptions` message in [descriptor.proto](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/descriptor.proto) for official documentation on these options. 312 313 * `ctype` 314 * `packed` 315 * `jstype` 316 * `lazy` 317 * `deprecated` 318 319 #### Oneof Descriptor 320 321 * `name`: name of the oneof. 322 * `full_name`: fully-qualified name of the oneof. 323 * [Comment fields](#comments) 324 325 #### Enum Descriptor 326 327 * `name`: name of the enum. 328 * `full_name`: fully-qualified name of the enum. 329 * `description`: comment before (but attached to) the enum declaration. 330 * [Comment fields](#comments): see the [Comments](#comments) section. 331 * `defined_in`: the name of the file the enum is declared in. 332 333 ##### Enum Options 334 335 See the `EnumOptions` message in [descriptor.proto](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/descriptor.proto) for official documentation on these options. 336 337 * `allow_alias` 338 * `deprecated` 339 340 #### Enum Value Descriptor 341 342 * `name`: the name of the enum value. 343 * `number`: the number of the enum value. 344 * `options`: an [enum options descriptor](#enum-value-options). 345 * `custom_options`: a map of [custom options](#custom_options). 346 * [Comment fields](#comments): see the [Comments](#comments) section. 347 348 #### Enum Value Options 349 350 See the `EnumValueOptions` message in [descriptor.proto](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/descriptor.proto) for official documentation on this option. 351 352 * `deprecated` 353 354 #### Extension Descriptor 355 356 * `name`: name of the extension. E.g., "field_required". 357 * `full_name`: fully-qualified name of the extension. E.g., "MyServices.Tester.field_required". 358 * `field_number`: the field number/slot number for this field. E.g., 51234. 359 * `type`: type of the field in the extension. E.g., "bool". 360 * `extendee`: the extended protobuf message name. E.g., "google.protobuf.MessageOptions". 361 * [Comment fields](#comments): see the [Comments](#comments) section. 362 * `defined_in`: the name of the file the extension is declared in. 363 364 ## Glossary 365 366 * Descriptor: a data structure describing a thing. Descriptors described in this document are not the same structures as the protobuf descriptors used for the output of this plugin, but they tend to be modeled after them. 367 * Fully-qualified name: a name prefixed with the package name, and, if applicable, the parent message name, etc.