├── .devcontainer ├── Dockerfile └── devcontainer.json ├── .github ├── dependabot.yml └── workflows │ ├── check-go.yml │ └── kolla-build-devcontainer.yml ├── .gitignore ├── LICENSE ├── README.md ├── examples ├── envoy │ └── validate.proto ├── google │ ├── api │ │ ├── annotations.proto │ │ ├── client.proto │ │ ├── field_behavior.proto │ │ ├── http.proto │ │ ├── httpbody.proto │ │ └── resource.proto │ ├── example │ │ └── library │ │ │ └── v1 │ │ │ ├── library.proto │ │ │ ├── openapi.yaml │ │ │ └── openapi_json.yaml │ ├── httpbody.proto │ └── type │ │ ├── date.proto │ │ └── datetime.proto └── tests │ ├── bodymapping │ ├── message.proto │ ├── openapi.yaml │ └── openapi_json.yaml │ ├── customparams │ ├── message.proto │ ├── openapi.yaml │ └── openapi_json.yaml │ ├── customparamsbuildtag │ ├── message.proto │ ├── openapi.yaml │ └── openapi_json.yaml │ ├── customparamsexample │ ├── message.proto │ ├── openapi.yaml │ └── openapi_json.yaml │ ├── customparamsexclude │ ├── message.proto │ ├── openapi.yaml │ └── openapi_json.yaml │ ├── customparamspostmanandpublic │ ├── message.proto │ ├── openapi.yaml │ └── openapi_json.yaml │ ├── customparamspostmanonly │ ├── message.proto │ ├── openapi.yaml │ └── openapi_json.yaml │ ├── enums │ ├── message.proto │ ├── openapi.yaml │ └── openapi_json.yaml │ ├── fieldbehaviors │ ├── message.proto │ ├── openapi.yaml │ └── openapi_json.yaml │ ├── jsonoptions │ ├── message.proto │ ├── openapi.yaml │ └── openapi_json.yaml │ ├── mapfields │ ├── message.proto │ ├── openapi.yaml │ └── openapi_json.yaml │ ├── messagenamepattern │ ├── message.proto │ ├── openapi.yaml │ └── openapi_json.yaml │ ├── noannotations │ ├── message.proto │ ├── openapi.yaml │ └── openapi_json.yaml │ ├── pathparams │ ├── message.proto │ ├── openapi.yaml │ └── openapi_json.yaml │ ├── protobuftypes │ ├── message.proto │ ├── openapi.yaml │ └── openapi_json.yaml │ ├── summary │ ├── message.proto │ ├── openapi.yaml │ └── openapi_json.yaml │ └── validate │ ├── message.proto │ ├── openapi.yaml │ └── openapi_json.yaml ├── gen.sh ├── generator ├── enum.go ├── openapi-v3.go ├── reflector.go ├── utils.go ├── utils_test.go └── validate.go ├── go.mod ├── go.sum ├── main.go ├── main_test.go ├── openapi ├── annotations.pb.go └── annotations.proto ├── plugin_test.go └── run_tests /.devcontainer/Dockerfile: -------------------------------------------------------------------------------- 1 | FROM mcr.microsoft.com/devcontainers/base:bullseye 2 | 3 | ARG TARGETARCH 4 | ARG DEBIAN_FRONTEND=noninteractive 5 | 6 | # uname typically returns either x86_64 or aarch64 7 | # Install protoc (x86_64 || aarch_64) 8 | RUN PB_REL="https://github.com/protocolbuffers/protobuf/releases" && \ 9 | NAME="protoc" && VERSION="22.0" && \ 10 | ARCH=$(uname -m); \ 11 | if [ $ARCH = 'aarch64' ]; then ARCH='aarch_64'; fi; \ 12 | curl -L -o ${NAME}.zip ${PB_REL}/download/v${VERSION}/${NAME}-${VERSION}-linux-${ARCH}.zip && \ 13 | unzip ${NAME}.zip -d /tmp && \ 14 | cp -R /tmp/include/google /usr/local/include/ && \ 15 | chmod -R +xr /usr/local/include/google && \ 16 | cp /tmp/bin/* /usr/local/bin/ && \ 17 | chmod +x /usr/local/bin/${NAME} && \ 18 | rm -f ${NAME}.zip 19 | 20 | 21 | RUN mkdir -p /go/pkg && mkdir -p /go/bin && chmod og+w -R /go 22 | -------------------------------------------------------------------------------- /.devcontainer/devcontainer.json: -------------------------------------------------------------------------------- 1 | // For format details, see https://aka.ms/devcontainer.json. For config options, see the 2 | // README at: https://github.com/devcontainers/templates/tree/main/src/go 3 | { 4 | "name": "Debian", 5 | // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile 6 | "features": { 7 | "ghcr.io/dhoeric/features/google-cloud-cli:1": {}, 8 | "ghcr.io/devcontainers/features/go:1": { 9 | "version": "1.24" 10 | } 11 | }, 12 | "build": { 13 | "dockerfile": "Dockerfile", 14 | "cacheFrom": [ 15 | "ghcr.io/kollalabs/protoc-gen-openapi:devcontainer" 16 | ] 17 | }, 18 | // Configure tool-specific properties. 19 | "customizations": { 20 | // Configure properties specific to VS Code. 21 | "vscode": { 22 | // Add the IDs of extensions you want installed when the container is created. 23 | "extensions": [ 24 | "golang.Go", 25 | "zxh404.vscode-proto3", 26 | "GitHub.copilot" 27 | ] 28 | } 29 | }, 30 | // Use 'forwardPorts' to make a list of ports inside the container available locally. 31 | // "forwardPorts": [], 32 | // Use 'postCreateCommand' to run commands after the container is created. 33 | "postCreateCommand": "go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.35.1", 34 | // Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root. 35 | "remoteUser": "vscode" 36 | } -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | # To get started with Dependabot version updates, you'll need to specify which 2 | # package ecosystems to update and where the package manifests are located. 3 | # Please see the documentation for all configuration options: 4 | # https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates 5 | 6 | version: 2 7 | updates: 8 | - package-ecosystem: "docker" # See documentation for possible values 9 | directory: "/.devcontainer" # Location of package manifests 10 | schedule: 11 | interval: "daily" 12 | - package-ecosystem: "github-actions" 13 | directory: "/" 14 | schedule: 15 | interval: "daily" 16 | - package-ecosystem: "gomod" # See documentation for possible values 17 | directory: "/" # Location of package manifests 18 | schedule: 19 | interval: "daily" 20 | -------------------------------------------------------------------------------- /.github/workflows/check-go.yml: -------------------------------------------------------------------------------- 1 | name: Run go tests 2 | 3 | on: 4 | push: 5 | branches: [main] 6 | pull_request: 7 | branches: [main] 8 | 9 | jobs: 10 | devcontainer: 11 | uses: kollalabs/protoc-gen-openapi/.github/workflows/kolla-build-devcontainer.yml@main 12 | 13 | check-gen: 14 | runs-on: ubuntu-latest 15 | needs: 16 | - devcontainer 17 | container: 18 | image: ${{ needs.devcontainer.outputs.devcontainer-image }} 19 | options: --user 1001 20 | 21 | steps: 22 | - uses: actions/checkout@v4 23 | - name: Go build and Test 24 | shell: bash 25 | run: | 26 | # load the devcontainer dockerfile and run the generate commands 27 | # make sure that git isn't dirty after running generate 28 | 29 | go build 30 | 31 | go vet 32 | 33 | go test 34 | -------------------------------------------------------------------------------- /.github/workflows/kolla-build-devcontainer.yml: -------------------------------------------------------------------------------- 1 | name: Setup Devcontainer 2 | 3 | on: 4 | workflow_call: 5 | outputs: 6 | devcontainer-image: 7 | description: "Devcontainer image path to use" 8 | value: ${{ jobs.has-changes.outputs.devcontainer-image }} 9 | 10 | jobs: 11 | has-changes: 12 | runs-on: ubuntu-latest 13 | outputs: 14 | has-changes: ${{ steps.changes.outputs.has-changes }} 15 | devcontainer-image: ${{ steps.changes.outputs.devcontainer-image }} 16 | 17 | steps: 18 | - name: Checkout current branch 19 | uses: actions/checkout@v4 20 | 21 | - name: Check if devcontainer has changed 22 | id: changes 23 | shell: bash 24 | run: | 25 | set -ux 26 | set +e 27 | 28 | git fetch --depth 1 origin main 29 | git diff --exit-code --name-only origin/main ./.devcontainer 30 | STATUS=$? 31 | set -e 32 | 33 | if [ $STATUS -eq 0 ]; then 34 | echo "::set-output name=has-changes::false" 35 | echo "::set-output name=devcontainer-image::ghcr.io/kollalabs/protoc-gen-openapi:devcontainer" 36 | else 37 | echo "::set-output name=has-changes::true" 38 | echo "::set-output name=devcontainer-image::ghcr.io/kollalabs/protoc-gen-openapi:devcontainer" 39 | fi 40 | 41 | build: 42 | runs-on: ubuntu-latest 43 | needs: 44 | - has-changes 45 | if: ${{ needs.has-changes.outputs.has-changes == 'true' }} 46 | steps: 47 | - uses: actions/checkout@v4 48 | 49 | - name: Set up Docker BuildKit 50 | uses: docker/setup-buildx-action@v3 51 | 52 | - name: Log in to registry 53 | run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u $ --password-stdin 54 | 55 | - name: Build and publish the devcontainer 56 | run: | 57 | set -eux 58 | 59 | # install devcontainer cli 60 | npm install -g @vscode/dev-container-cli 61 | 62 | # install devcontainer cli 63 | npm install -g @vscode/dev-container-cli 64 | 65 | IMAGE=${{ needs.has-changes.outputs.devcontainer-image }} 66 | # TODO inject cache from entry for current branch if we're on a branch 67 | docker pull ${IMAGE} || true 68 | 69 | #TODO: if we're on a branch inject container image into .devcontainer.json as a cacheFrom target 70 | # jq append to build.cacheFrom 71 | devcontainer build --image-name=${IMAGE} 72 | 73 | docker push ${IMAGE} 74 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | /protoc-gen-openapi 2 | /openapi.yaml 3 | 4 | # General 5 | .DS_Store 6 | .AppleDouble 7 | .LSOverride 8 | 9 | # Icon must end with two \r 10 | Icon 11 | 12 | 13 | # Thumbnails 14 | ._* 15 | 16 | # Files that might appear in the root of a volume 17 | .DocumentRevisions-V100 18 | .fseventsd 19 | .Spotlight-V100 20 | .TemporaryItems 21 | .Trashes 22 | .VolumeIcon.icns 23 | .com.apple.timemachine.donotpresent 24 | 25 | # Directories potentially created on remote AFP share 26 | .AppleDB 27 | .AppleDesktop 28 | Network Trash Folder 29 | Temporary Items 30 | .apdisk 31 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # protoc-gen-openapi 2 | 3 | Contains a protoc plugin that generates openapi v3 documents 4 | 5 | **Forked from [github.com/google/gnostic/cmd/protoc-gen-openapi](https://github.com/google/gnostic/tree/main/cmd/protoc-gen-openapi)** 6 | 7 | Installation: 8 | 9 | go install github.com/kollalabs/protoc-gen-openapi@latest 10 | 11 | Usage: 12 | 13 | protoc sample.proto -I. --openapi_out=version=1.2.3:. 14 | 15 | ## Testing 16 | 17 | To see output during tests use `log.Print*` 18 | 19 | ``` 20 | go clean -testcache && go test 21 | ``` 22 | 23 | ## Added Features 24 | We have added some features that the Gnostic team most likely doesn't want to add :-) 25 | Some are fairly Kolla specific, sorry. We try to hide Kolla specific functionality 26 | in a way that won't trip anyone up. 27 | 28 | * [Better Enum Support](#better-enum-support) 29 | * [Summary Field](#summary-field) 30 | * [Validation (protoc-gen-validate)](#validation) 31 | * [Google Field Behavior Annotations](#google-field-behavior-annotations) 32 | * [OAS3 header support](#oas3-header-support) 33 | 34 | ### Better Enum Support 35 | Enums work better by using string values of proto enums instead of ints. 36 | 37 | ### Summary Field 38 | 39 | Sometimes you want more control over certain properties in the OpenAPI manifest. In our 40 | case we wanted to use the `summary` property on routes to look nice for generating 41 | documentation from the OpenAPI manifest. Normally the summary comes simply from the 42 | name of the route. We added a feature that parses the comment over the proto service 43 | method and looks for a pipe character ("`|`") and if it sees it, it will take anything to 44 | the left of it and put it in the `summary` field, and anything to the right of it will 45 | be the `description`. If no pipe is found it puts the whole comment in the description 46 | like normal. From `/examples/tests/summary/message.proto`: 47 | 48 | ```proto 49 | service Messaging { 50 | // Update Message Summary | This function updates a message. 51 | rpc UpdateMessage(Message) returns(Message) { 52 | option(google.api.http) = { 53 | patch: "/v1/messages/{message_id}" 54 | body: "text" 55 | }; 56 | } 57 | } 58 | ``` 59 | 60 | It generates the following OpenAPI: 61 | 62 | ```yaml 63 | #... 64 | paths: 65 | /v1/messages/{message_id}: 66 | patch: 67 | tags: 68 | - Messaging 69 | summary: Update Message Summary # Look at this beautiful summary... 70 | description: This function updates a message. 71 | #... 72 | ``` 73 | 74 | ### Validation 75 | 76 | We added partial support for `protoc-gen-validate` annotations 77 | 78 | OpenAPI spec allows for a small handful of input validation configurations. 79 | Proto has an awesome plugin called `protoc-gen-validate` for generating validation code in 80 | Go, Java, C++, etc. We took those same annotations and added support in this project 81 | for them. 82 | 83 | Usage: add `validate=true` to protoc command. 84 | 85 | `protoc sample.proto -I. --openapi_out=version=1.2.3,validate=true:.` 86 | 87 | #### Example 88 | 89 | ```proto 90 | message Message { 91 | string message_id = 1; 92 | string text = 2 [(validate.rules)= { 93 | string: { 94 | uri:true, 95 | max_len:45, 96 | min_len:1 97 | } 98 | }]; 99 | int64 mynum = 3 [(validate.rules).int64 = {gte:1, lte:30}]; 100 | } 101 | 102 | ``` 103 | 104 | outputs: 105 | 106 | ```yaml 107 | components: 108 | schemas: 109 | Message: 110 | properties: 111 | message_id: 112 | type: string 113 | text: 114 | maxLength: 45 115 | minLength: 1 116 | type: string 117 | format: uri 118 | mynum: 119 | maximum: !!float 30 120 | minimum: !!float 1 121 | type: integer 122 | format: int64 123 | 124 | ``` 125 | 126 | #### Supported Validators 127 | 128 | String 129 | - uri 130 | - uuid 131 | - email 132 | - ipv4 133 | - ipv6 134 | - max_len 135 | - min_len 136 | 137 | Int32 138 | - gte 139 | - lte 140 | 141 | Int64 142 | - gte 143 | - lte 144 | 145 | Adding more can easily be done in the function `addValidationRules` in `/generator/openapi-v3.yaml` 146 | 147 | ### Google Field Behavior Annotations 148 | 149 | * `(google.api.field_behavior) = REQUIRED` will add the field to the required list in the openAPI schema 150 | * `(google.api.field_behavior) = OUTPUT_ONLY` will add the `readOnly` property to the field 151 | * `(google.api.field_behavior) = INPUT_ONLY` will add the `writeOnly` property to the field 152 | * TODO: `(google.api.field_behavior) = IMMUTABLE` will add the `x-createOnly` property to the field (not supported by openapi yet) 153 | 154 | ### OAS3 header support 155 | 156 | -------------------------------------------------------------------------------- /examples/google/api/annotations.proto: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2015, Google Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | syntax = "proto3"; 16 | 17 | package google.api; 18 | 19 | import "google/api/http.proto"; 20 | import "google/protobuf/descriptor.proto"; 21 | 22 | option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations"; 23 | option java_multiple_files = true; 24 | option java_outer_classname = "AnnotationsProto"; 25 | option java_package = "com.google.api"; 26 | option objc_class_prefix = "GAPI"; 27 | 28 | extend google.protobuf.MethodOptions { 29 | // See `HttpRule`. 30 | HttpRule http = 72295728; 31 | } 32 | -------------------------------------------------------------------------------- /examples/google/api/client.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2019 Google LLC. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // https://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | syntax = "proto3"; 16 | 17 | package google.api; 18 | 19 | import "google/protobuf/descriptor.proto"; 20 | 21 | option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations"; 22 | option java_multiple_files = true; 23 | option java_outer_classname = "ClientProto"; 24 | option java_package = "com.google.api"; 25 | option objc_class_prefix = "GAPI"; 26 | 27 | 28 | extend google.protobuf.ServiceOptions { 29 | // The hostname for this service. 30 | // This should be specified with no prefix or protocol. 31 | // 32 | // Example: 33 | // 34 | // service Foo { 35 | // option (google.api.default_host) = "foo.googleapi.com"; 36 | // ... 37 | // } 38 | string default_host = 1049; 39 | 40 | // OAuth scopes needed for the client. 41 | // 42 | // Example: 43 | // 44 | // service Foo { 45 | // option (google.api.oauth_scopes) = \ 46 | // "https://www.googleapis.com/auth/cloud-platform"; 47 | // ... 48 | // } 49 | // 50 | // If there is more than one scope, use a comma-separated string: 51 | // 52 | // Example: 53 | // 54 | // service Foo { 55 | // option (google.api.oauth_scopes) = \ 56 | // "https://www.googleapis.com/auth/cloud-platform," 57 | // "https://www.googleapis.com/auth/monitoring"; 58 | // ... 59 | // } 60 | string oauth_scopes = 1050; 61 | } 62 | 63 | 64 | extend google.protobuf.MethodOptions { 65 | // A definition of a client library method signature. 66 | // 67 | // In client libraries, each proto RPC corresponds to one or more methods 68 | // which the end user is able to call, and calls the underlying RPC. 69 | // Normally, this method receives a single argument (a struct or instance 70 | // corresponding to the RPC request object). Defining this field will 71 | // add one or more overloads providing flattened or simpler method signatures 72 | // in some languages. 73 | // 74 | // The fields on the method signature are provided as a comma-separated 75 | // string. 76 | // 77 | // For example, the proto RPC and annotation: 78 | // 79 | // rpc CreateSubscription(CreateSubscriptionRequest) 80 | // returns (Subscription) { 81 | // option (google.api.method_signature) = "name,topic"; 82 | // } 83 | // 84 | // Would add the following Java overload (in addition to the method accepting 85 | // the request object): 86 | // 87 | // public final Subscription createSubscription(String name, String topic) 88 | // 89 | // The following backwards-compatibility guidelines apply: 90 | // 91 | // * Adding this annotation to an unannotated method is backwards 92 | // compatible. 93 | // * Adding this annotation to a method which already has existing 94 | // method signature annotations is backwards compatible if and only if 95 | // the new method signature annotation is last in the sequence. 96 | // * Modifying or removing an existing method signature annotation is 97 | // a breaking change. 98 | // * Re-ordering existing method signature annotations is a breaking 99 | // change. 100 | repeated string method_signature = 1051; 101 | } 102 | -------------------------------------------------------------------------------- /examples/google/api/field_behavior.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2019 Google LLC. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // https://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | syntax = "proto3"; 16 | 17 | package google.api; 18 | 19 | import "google/protobuf/descriptor.proto"; 20 | 21 | option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations"; 22 | option java_multiple_files = true; 23 | option java_outer_classname = "FieldBehaviorProto"; 24 | option java_package = "com.google.api"; 25 | option objc_class_prefix = "GAPI"; 26 | 27 | 28 | // An indicator of the behavior of a given field (for example, that a field 29 | // is required in requests, or given as output but ignored as input). 30 | // This **does not** change the behavior in protocol buffers itself; it only 31 | // denotes the behavior and may affect how API tooling handles the field. 32 | // 33 | // Note: This enum **may** receive new values in the future. 34 | enum FieldBehavior { 35 | // Conventional default for enums. Do not use this. 36 | FIELD_BEHAVIOR_UNSPECIFIED = 0; 37 | 38 | // Specifically denotes a field as optional. 39 | // While all fields in protocol buffers are optional, this may be specified 40 | // for emphasis if appropriate. 41 | OPTIONAL = 1; 42 | 43 | // Denotes a field as required. 44 | // This indicates that the field **must** be provided as part of the request, 45 | // and failure to do so will cause an error (usually `INVALID_ARGUMENT`). 46 | REQUIRED = 2; 47 | 48 | // Denotes a field as output only. 49 | // This indicates that the field is provided in responses, but including the 50 | // field in a request does nothing (the server *must* ignore it and 51 | // *must not* throw an error as a result of the field's presence). 52 | OUTPUT_ONLY = 3; 53 | 54 | // Denotes a field as input only. 55 | // This indicates that the field is provided in requests, and the 56 | // corresponding field is not included in output. 57 | INPUT_ONLY = 4; 58 | 59 | // Denotes a field as immutable. 60 | // This indicates that the field may be set once in a request to create a 61 | // resource, but may not be changed thereafter. 62 | IMMUTABLE = 5; 63 | } 64 | 65 | 66 | extend google.protobuf.FieldOptions { 67 | // A designation of a specific field behavior (required, output only, etc.) 68 | // in protobuf messages. 69 | // 70 | // Examples: 71 | // 72 | // string name = 1 [(google.api.field_behavior) = REQUIRED]; 73 | // State state = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; 74 | // google.protobuf.Duration ttl = 1 75 | // [(google.api.field_behavior) = INPUT_ONLY]; 76 | // google.protobuf.Timestamp expire_time = 1 77 | // [(google.api.field_behavior) = OUTPUT_ONLY, 78 | // (google.api.field_behavior) = IMMUTABLE]; 79 | repeated FieldBehavior field_behavior = 1052; 80 | } 81 | -------------------------------------------------------------------------------- /examples/google/api/httpbody.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2015 Google LLC 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | syntax = "proto3"; 16 | 17 | package google.api; 18 | 19 | import "google/protobuf/any.proto"; 20 | 21 | option cc_enable_arenas = true; 22 | option go_package = "google.golang.org/genproto/googleapis/api/httpbody;httpbody"; 23 | option java_multiple_files = true; 24 | option java_outer_classname = "HttpBodyProto"; 25 | option java_package = "com.google.api"; 26 | option objc_class_prefix = "GAPI"; 27 | 28 | // Message that represents an arbitrary HTTP body. It should only be used for 29 | // payload formats that can't be represented as JSON, such as raw binary or 30 | // an HTML page. 31 | // 32 | // 33 | // This message can be used both in streaming and non-streaming API methods in 34 | // the request as well as the response. 35 | // 36 | // It can be used as a top-level request field, which is convenient if one 37 | // wants to extract parameters from either the URL or HTTP template into the 38 | // request fields and also want access to the raw HTTP body. 39 | // 40 | // Example: 41 | // 42 | // message GetResourceRequest { 43 | // // A unique request id. 44 | // string request_id = 1; 45 | // 46 | // // The raw HTTP body is bound to this field. 47 | // google.api.HttpBody http_body = 2; 48 | // 49 | // } 50 | // 51 | // service ResourceService { 52 | // rpc GetResource(GetResourceRequest) 53 | // returns (google.api.HttpBody); 54 | // rpc UpdateResource(google.api.HttpBody) 55 | // returns (google.protobuf.Empty); 56 | // 57 | // } 58 | // 59 | // Example with streaming methods: 60 | // 61 | // service CaldavService { 62 | // rpc GetCalendar(stream google.api.HttpBody) 63 | // returns (stream google.api.HttpBody); 64 | // rpc UpdateCalendar(stream google.api.HttpBody) 65 | // returns (stream google.api.HttpBody); 66 | // 67 | // } 68 | // 69 | // Use of this type only changes how the request and response bodies are 70 | // handled, all other features will continue to work unchanged. 71 | message HttpBody { 72 | // The HTTP Content-Type header value specifying the content type of the body. 73 | string content_type = 1; 74 | 75 | // The HTTP request/response body as raw binary. 76 | bytes data = 2; 77 | 78 | // Application specific response metadata. Must be set in the first response 79 | // for streaming APIs. 80 | repeated google.protobuf.Any extensions = 3; 81 | } -------------------------------------------------------------------------------- /examples/google/httpbody.proto: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kollalabs/protoc-gen-openapi/3096882eb60bc60ca7ac66b06c1e2d18f11e0b52/examples/google/httpbody.proto -------------------------------------------------------------------------------- /examples/google/type/date.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2020 Google LLC 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | syntax = "proto3"; 16 | 17 | package google.type; 18 | 19 | option cc_enable_arenas = true; 20 | option go_package = "google.golang.org/genproto/googleapis/type/date;date"; 21 | option java_multiple_files = true; 22 | option java_outer_classname = "DateProto"; 23 | option java_package = "com.google.type"; 24 | option objc_class_prefix = "GTP"; 25 | 26 | // Represents a whole or partial calendar date, such as a birthday. The time of 27 | // day and time zone are either specified elsewhere or are insignificant. The 28 | // date is relative to the Gregorian Calendar. This can represent one of the 29 | // following: 30 | // 31 | // * A full date, with non-zero year, month, and day values 32 | // * A month and day value, with a zero year, such as an anniversary 33 | // * A year on its own, with zero month and day values 34 | // * A year and month value, with a zero day, such as a credit card expiration 35 | // date 36 | // 37 | // Related types are [google.type.TimeOfDay][google.type.TimeOfDay] and `google.protobuf.Timestamp`. 38 | message Date { 39 | // Year of the date. Must be from 1 to 9999, or 0 to specify a date without 40 | // a year. 41 | int32 year = 1; 42 | 43 | // Month of a year. Must be from 1 to 12, or 0 to specify a year without a 44 | // month and day. 45 | int32 month = 2; 46 | 47 | // Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 48 | // to specify a year by itself or a year and month where the day isn't 49 | // significant. 50 | int32 day = 3; 51 | } 52 | -------------------------------------------------------------------------------- /examples/google/type/datetime.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2020 Google LLC 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | syntax = "proto3"; 16 | 17 | package google.type; 18 | 19 | import "google/protobuf/duration.proto"; 20 | 21 | option cc_enable_arenas = true; 22 | option go_package = "google.golang.org/genproto/googleapis/type/datetime;datetime"; 23 | option java_multiple_files = true; 24 | option java_outer_classname = "DateTimeProto"; 25 | option java_package = "com.google.type"; 26 | option objc_class_prefix = "GTP"; 27 | 28 | // Represents civil time (or occasionally physical time). 29 | // 30 | // This type can represent a civil time in one of a few possible ways: 31 | // 32 | // * When utc_offset is set and time_zone is unset: a civil time on a calendar 33 | // day with a particular offset from UTC. 34 | // * When time_zone is set and utc_offset is unset: a civil time on a calendar 35 | // day in a particular time zone. 36 | // * When neither time_zone nor utc_offset is set: a civil time on a calendar 37 | // day in local time. 38 | // 39 | // The date is relative to the Proleptic Gregorian Calendar. 40 | // 41 | // If year is 0, the DateTime is considered not to have a specific year. month 42 | // and day must have valid, non-zero values. 43 | // 44 | // This type may also be used to represent a physical time if all the date and 45 | // time fields are set and either case of the `time_offset` oneof is set. 46 | // Consider using `Timestamp` message for physical time instead. If your use 47 | // case also would like to store the user's timezone, that can be done in 48 | // another field. 49 | // 50 | // This type is more flexible than some applications may want. Make sure to 51 | // document and validate your application's limitations. 52 | message DateTime { 53 | // Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a 54 | // datetime without a year. 55 | int32 year = 1; 56 | 57 | // Required. Month of year. Must be from 1 to 12. 58 | int32 month = 2; 59 | 60 | // Required. Day of month. Must be from 1 to 31 and valid for the year and 61 | // month. 62 | int32 day = 3; 63 | 64 | // Required. Hours of day in 24 hour format. Should be from 0 to 23. An API 65 | // may choose to allow the value "24:00:00" for scenarios like business 66 | // closing time. 67 | int32 hours = 4; 68 | 69 | // Required. Minutes of hour of day. Must be from 0 to 59. 70 | int32 minutes = 5; 71 | 72 | // Required. Seconds of minutes of the time. Must normally be from 0 to 59. An 73 | // API may allow the value 60 if it allows leap-seconds. 74 | int32 seconds = 6; 75 | 76 | // Required. Fractions of seconds in nanoseconds. Must be from 0 to 77 | // 999,999,999. 78 | int32 nanos = 7; 79 | 80 | // Optional. Specifies either the UTC offset or the time zone of the DateTime. 81 | // Choose carefully between them, considering that time zone data may change 82 | // in the future (for example, a country modifies their DST start/end dates, 83 | // and future DateTimes in the affected range had already been stored). 84 | // If omitted, the DateTime is considered to be in local time. 85 | oneof time_offset { 86 | // UTC offset. Must be whole seconds, between -18 hours and +18 hours. 87 | // For example, a UTC offset of -4:00 would be represented as 88 | // { seconds: -14400 }. 89 | google.protobuf.Duration utc_offset = 8; 90 | 91 | // Time zone. 92 | TimeZone time_zone = 9; 93 | } 94 | } 95 | 96 | // Represents a time zone from the 97 | // [IANA Time Zone Database](https://www.iana.org/time-zones). 98 | message TimeZone { 99 | // IANA Time Zone Database time zone, e.g. "America/New_York". 100 | string id = 1; 101 | 102 | // Optional. IANA Time Zone Database version number, e.g. "2019a". 103 | string version = 2; 104 | } 105 | -------------------------------------------------------------------------------- /examples/tests/bodymapping/message.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2020 Google LLC. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | // 15 | 16 | syntax = "proto3"; 17 | 18 | package tests.bodymappying.message.v1; 19 | 20 | import "google/api/annotations.proto"; 21 | 22 | option go_package = "github.com/google/gnostic/apps/protoc-gen-openapi/examples/tests/bodymapping/message/v1;message"; 23 | 24 | service Messaging { 25 | rpc UpdateMessage(Message) returns(Message) { 26 | option(google.api.http) = { 27 | patch: "/v1/messages/{message_id}" 28 | body: "text" 29 | }; 30 | } 31 | } 32 | message Message { 33 | string message_id = 1; 34 | string text = 2; 35 | } 36 | -------------------------------------------------------------------------------- /examples/tests/bodymapping/openapi.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 0.0.1 8 | paths: 9 | /v1/messages/{message_id}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: UpdateMessage 14 | operationId: Messaging_UpdateMessage 15 | parameters: 16 | - name: message_id 17 | in: path 18 | required: true 19 | schema: 20 | type: string 21 | requestBody: 22 | content: 23 | application/json: 24 | schema: 25 | type: string 26 | required: true 27 | responses: 28 | "200": 29 | description: OK 30 | content: 31 | application/json: 32 | schema: 33 | $ref: '#/components/schemas/Message' 34 | default: 35 | description: Default error response 36 | content: 37 | application/json: 38 | schema: 39 | $ref: '#/components/schemas/Status' 40 | components: 41 | schemas: 42 | GoogleProtobufAny: 43 | type: object 44 | properties: 45 | '@type': 46 | type: string 47 | description: The type of the serialized message. 48 | additionalProperties: true 49 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 50 | Message: 51 | type: object 52 | properties: 53 | message_id: 54 | type: string 55 | text: 56 | type: string 57 | Status: 58 | type: object 59 | properties: 60 | code: 61 | type: integer 62 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 63 | format: int32 64 | message: 65 | type: string 66 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 67 | details: 68 | type: array 69 | items: 70 | $ref: '#/components/schemas/GoogleProtobufAny' 71 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 72 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 73 | tags: 74 | - name: Messaging 75 | -------------------------------------------------------------------------------- /examples/tests/bodymapping/openapi_json.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 1.2.3 8 | paths: 9 | /v1/messages/{messageId}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: UpdateMessage 14 | operationId: Messaging_UpdateMessage 15 | parameters: 16 | - name: messageId 17 | in: path 18 | required: true 19 | schema: 20 | type: string 21 | requestBody: 22 | content: 23 | application/json: 24 | schema: 25 | type: string 26 | required: true 27 | responses: 28 | "200": 29 | description: OK 30 | content: 31 | application/json: 32 | schema: 33 | $ref: '#/components/schemas/Message' 34 | default: 35 | description: Default error response 36 | content: 37 | application/json: 38 | schema: 39 | $ref: '#/components/schemas/Status' 40 | components: 41 | schemas: 42 | GoogleProtobufAny: 43 | type: object 44 | properties: 45 | '@type': 46 | type: string 47 | description: The type of the serialized message. 48 | additionalProperties: true 49 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 50 | Message: 51 | type: object 52 | properties: 53 | messageId: 54 | type: string 55 | text: 56 | type: string 57 | Status: 58 | type: object 59 | properties: 60 | code: 61 | type: integer 62 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 63 | format: int32 64 | message: 65 | type: string 66 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 67 | details: 68 | type: array 69 | items: 70 | $ref: '#/components/schemas/GoogleProtobufAny' 71 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 72 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 73 | tags: 74 | - name: Messaging 75 | -------------------------------------------------------------------------------- /examples/tests/customparams/message.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2020 Google LLC. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | // 15 | 16 | syntax = "proto3"; 17 | 18 | package tests.customparams.message.v1; 19 | 20 | import "google/api/annotations.proto"; 21 | import "openapi/annotations.proto"; 22 | 23 | option go_package = "github.com/google/gnostic/apps/protoc-gen-openapi/examples/tests/bodymapping/message/v1;message"; 24 | 25 | option (openapi.file_params) = { headers: [{ name:"FileHeader" }]}; 26 | 27 | service Messaging { 28 | option (openapi.service_params) = {headers: 29 | [ 30 | { 31 | name:"ServiceHeader", 32 | pattern:"^(.*)$" 33 | description:"This is a service header" 34 | required:true 35 | } 36 | ] 37 | }; 38 | // Update Message Summary | This function updates a message. 39 | // (-- api-linter: core::0xxx::xxx=disabled 40 | // aip.dev/not-precedent: We need to do this because reasons. --) 41 | rpc UpdateMessage(Message) returns(Message) { 42 | option (google.api.http) = { 43 | patch: "/v1/messages/{message_id}" 44 | body: "text" 45 | }; 46 | option (openapi.method_params) = { headers: [{name:"MethodHeader"}]}; 47 | } 48 | } 49 | message Message { 50 | string message_id = 1; 51 | string text = 2; 52 | } 53 | -------------------------------------------------------------------------------- /examples/tests/customparams/openapi.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 0.0.1 8 | paths: 9 | /v1/messages/{message_id}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: Update Message Summary 14 | description: This function updates a message. 15 | operationId: Messaging_UpdateMessage 16 | parameters: 17 | - name: message_id 18 | in: path 19 | required: true 20 | schema: 21 | type: string 22 | - name: ServiceHeader 23 | in: header 24 | description: This is a service header 25 | required: true 26 | schema: 27 | pattern: ^(.*)$ 28 | type: string 29 | requestBody: 30 | content: 31 | application/json: 32 | schema: 33 | type: string 34 | required: true 35 | responses: 36 | "200": 37 | description: OK 38 | content: 39 | application/json: 40 | schema: 41 | $ref: '#/components/schemas/Message' 42 | default: 43 | description: Default error response 44 | content: 45 | application/json: 46 | schema: 47 | $ref: '#/components/schemas/Status' 48 | components: 49 | schemas: 50 | GoogleProtobufAny: 51 | type: object 52 | properties: 53 | '@type': 54 | type: string 55 | description: The type of the serialized message. 56 | additionalProperties: true 57 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 58 | Message: 59 | type: object 60 | properties: 61 | message_id: 62 | type: string 63 | text: 64 | type: string 65 | Status: 66 | type: object 67 | properties: 68 | code: 69 | type: integer 70 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 71 | format: int32 72 | message: 73 | type: string 74 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 75 | details: 76 | type: array 77 | items: 78 | $ref: '#/components/schemas/GoogleProtobufAny' 79 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 80 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 81 | tags: 82 | - name: Messaging 83 | -------------------------------------------------------------------------------- /examples/tests/customparams/openapi_json.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 1.2.3 8 | paths: 9 | /v1/messages/{messageId}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: Update Message Summary 14 | description: This function updates a message. 15 | operationId: Messaging_UpdateMessage 16 | parameters: 17 | - name: messageId 18 | in: path 19 | required: true 20 | schema: 21 | type: string 22 | - name: ServiceHeader 23 | in: header 24 | description: This is a service header 25 | required: true 26 | schema: 27 | pattern: ^(.*)$ 28 | type: string 29 | requestBody: 30 | content: 31 | application/json: 32 | schema: 33 | type: string 34 | required: true 35 | responses: 36 | "200": 37 | description: OK 38 | content: 39 | application/json: 40 | schema: 41 | $ref: '#/components/schemas/Message' 42 | default: 43 | description: Default error response 44 | content: 45 | application/json: 46 | schema: 47 | $ref: '#/components/schemas/Status' 48 | components: 49 | schemas: 50 | GoogleProtobufAny: 51 | type: object 52 | properties: 53 | '@type': 54 | type: string 55 | description: The type of the serialized message. 56 | additionalProperties: true 57 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 58 | Message: 59 | type: object 60 | properties: 61 | messageId: 62 | type: string 63 | text: 64 | type: string 65 | Status: 66 | type: object 67 | properties: 68 | code: 69 | type: integer 70 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 71 | format: int32 72 | message: 73 | type: string 74 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 75 | details: 76 | type: array 77 | items: 78 | $ref: '#/components/schemas/GoogleProtobufAny' 79 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 80 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 81 | tags: 82 | - name: Messaging 83 | -------------------------------------------------------------------------------- /examples/tests/customparamsbuildtag/message.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2020 Google LLC. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | // 15 | 16 | syntax = "proto3"; 17 | 18 | package tests.customparams.message.v1; 19 | 20 | import "google/api/annotations.proto"; 21 | import "openapi/annotations.proto"; 22 | 23 | option go_package = "github.com/google/gnostic/apps/protoc-gen-openapi/examples/tests/bodymapping/message/v1;message"; 24 | 25 | option (openapi.file_params) = { headers: [{ name:"FileHeader" }]}; 26 | 27 | service Messaging { 28 | option (openapi.service_params) = { 29 | headers: 30 | [ 31 | { 32 | name:"ServiceHeader", 33 | pattern:"^(.*)$" 34 | description:"This is a service header" 35 | required:true, 36 | } 37 | ], 38 | build_tags: ["postman"] 39 | }; 40 | // Update Message Summary | This function updates a message. 41 | // (-- api-linter: core::0xxx::xxx=disabled 42 | // aip.dev/not-precedent: We need to do this because reasons. --) 43 | rpc UpdateMessage(Message) returns(Message) { 44 | option (google.api.http) = { 45 | patch: "/v1/messages/{message_id}" 46 | body: "text" 47 | }; 48 | option (openapi.method_params) = { 49 | headers: [ 50 | { name:"MethodHeader"} 51 | ], 52 | build_tags: ["postman"] 53 | }; 54 | } 55 | } 56 | message Message { 57 | string message_id = 1; 58 | string text = 2; 59 | } 60 | -------------------------------------------------------------------------------- /examples/tests/customparamsbuildtag/openapi.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 0.0.1 8 | paths: 9 | /v1/messages/{message_id}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: Update Message Summary 14 | description: This function updates a message. 15 | operationId: Messaging_UpdateMessage 16 | parameters: 17 | - name: message_id 18 | in: path 19 | required: true 20 | schema: 21 | type: string 22 | - name: ServiceHeader 23 | in: header 24 | description: This is a service header 25 | required: true 26 | schema: 27 | pattern: ^(.*)$ 28 | type: string 29 | requestBody: 30 | content: 31 | application/json: 32 | schema: 33 | type: string 34 | required: true 35 | responses: 36 | "200": 37 | description: OK 38 | content: 39 | application/json: 40 | schema: 41 | $ref: '#/components/schemas/Message' 42 | default: 43 | description: Default error response 44 | content: 45 | application/json: 46 | schema: 47 | $ref: '#/components/schemas/Status' 48 | components: 49 | schemas: 50 | GoogleProtobufAny: 51 | type: object 52 | properties: 53 | '@type': 54 | type: string 55 | description: The type of the serialized message. 56 | additionalProperties: true 57 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 58 | Message: 59 | type: object 60 | properties: 61 | message_id: 62 | type: string 63 | text: 64 | type: string 65 | Status: 66 | type: object 67 | properties: 68 | code: 69 | type: integer 70 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 71 | format: int32 72 | message: 73 | type: string 74 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 75 | details: 76 | type: array 77 | items: 78 | $ref: '#/components/schemas/GoogleProtobufAny' 79 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 80 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 81 | tags: 82 | - name: Messaging 83 | -------------------------------------------------------------------------------- /examples/tests/customparamsbuildtag/openapi_json.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 1.2.3 8 | paths: 9 | /v1/messages/{messageId}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: Update Message Summary 14 | description: This function updates a message. 15 | operationId: Messaging_UpdateMessage 16 | parameters: 17 | - name: messageId 18 | in: path 19 | required: true 20 | schema: 21 | type: string 22 | requestBody: 23 | content: 24 | application/json: 25 | schema: 26 | type: string 27 | required: true 28 | responses: 29 | "200": 30 | description: OK 31 | content: 32 | application/json: 33 | schema: 34 | $ref: '#/components/schemas/Message' 35 | default: 36 | description: Default error response 37 | content: 38 | application/json: 39 | schema: 40 | $ref: '#/components/schemas/Status' 41 | components: 42 | schemas: 43 | GoogleProtobufAny: 44 | type: object 45 | properties: 46 | '@type': 47 | type: string 48 | description: The type of the serialized message. 49 | additionalProperties: true 50 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 51 | Message: 52 | type: object 53 | properties: 54 | messageId: 55 | type: string 56 | text: 57 | type: string 58 | Status: 59 | type: object 60 | properties: 61 | code: 62 | type: integer 63 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 64 | format: int32 65 | message: 66 | type: string 67 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 68 | details: 69 | type: array 70 | items: 71 | $ref: '#/components/schemas/GoogleProtobufAny' 72 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 73 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 74 | tags: 75 | - name: Messaging 76 | -------------------------------------------------------------------------------- /examples/tests/customparamsexample/message.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2020 Google LLC. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | // 15 | 16 | syntax = "proto3"; 17 | 18 | package tests.customparams.message.v1; 19 | 20 | import "google/api/annotations.proto"; 21 | import "openapi/annotations.proto"; 22 | 23 | option go_package = "github.com/google/gnostic/apps/protoc-gen-openapi/examples/tests/bodymapping/message/v1;message"; 24 | 25 | option (openapi.file_params) = { headers: [{ name:"FileHeader" }]}; 26 | 27 | service Messaging { 28 | option (openapi.service_params) = {headers: 29 | [ 30 | { 31 | name:"ServiceHeader", 32 | pattern:"^(.*)$" 33 | description:"This is a service header" 34 | required:true 35 | example:"\"{{consumer-id}}\"" 36 | } 37 | ] 38 | }; 39 | // Update Message Summary | This function updates a message. 40 | // (-- api-linter: core::0xxx::xxx=disabled 41 | // aip.dev/not-precedent: We need to do this because reasons. --) 42 | rpc UpdateMessage(Message) returns(Message) { 43 | option (google.api.http) = { 44 | patch: "/v1/messages/{message_id}" 45 | body: "text" 46 | }; 47 | option (openapi.method_params) = { headers: [{name:"MethodHeader"}]}; 48 | } 49 | } 50 | message Message { 51 | string message_id = 1; 52 | string text = 2; 53 | } 54 | -------------------------------------------------------------------------------- /examples/tests/customparamsexample/openapi.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 0.0.1 8 | paths: 9 | /v1/messages/{message_id}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: Update Message Summary 14 | description: This function updates a message. 15 | operationId: Messaging_UpdateMessage 16 | parameters: 17 | - name: message_id 18 | in: path 19 | required: true 20 | schema: 21 | type: string 22 | - name: ServiceHeader 23 | in: header 24 | description: This is a service header 25 | required: true 26 | schema: 27 | pattern: ^(.*)$ 28 | type: string 29 | example: "{{consumer-id}}" 30 | requestBody: 31 | content: 32 | application/json: 33 | schema: 34 | type: string 35 | required: true 36 | responses: 37 | "200": 38 | description: OK 39 | content: 40 | application/json: 41 | schema: 42 | $ref: '#/components/schemas/Message' 43 | default: 44 | description: Default error response 45 | content: 46 | application/json: 47 | schema: 48 | $ref: '#/components/schemas/Status' 49 | components: 50 | schemas: 51 | GoogleProtobufAny: 52 | type: object 53 | properties: 54 | '@type': 55 | type: string 56 | description: The type of the serialized message. 57 | additionalProperties: true 58 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 59 | Message: 60 | type: object 61 | properties: 62 | message_id: 63 | type: string 64 | text: 65 | type: string 66 | Status: 67 | type: object 68 | properties: 69 | code: 70 | type: integer 71 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 72 | format: int32 73 | message: 74 | type: string 75 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 76 | details: 77 | type: array 78 | items: 79 | $ref: '#/components/schemas/GoogleProtobufAny' 80 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 81 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 82 | tags: 83 | - name: Messaging 84 | -------------------------------------------------------------------------------- /examples/tests/customparamsexample/openapi_json.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 1.2.3 8 | paths: 9 | /v1/messages/{messageId}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: Update Message Summary 14 | description: This function updates a message. 15 | operationId: Messaging_UpdateMessage 16 | parameters: 17 | - name: messageId 18 | in: path 19 | required: true 20 | schema: 21 | type: string 22 | - name: ServiceHeader 23 | in: header 24 | description: This is a service header 25 | required: true 26 | schema: 27 | pattern: ^(.*)$ 28 | type: string 29 | requestBody: 30 | content: 31 | application/json: 32 | schema: 33 | type: string 34 | required: true 35 | responses: 36 | "200": 37 | description: OK 38 | content: 39 | application/json: 40 | schema: 41 | $ref: '#/components/schemas/Message' 42 | default: 43 | description: Default error response 44 | content: 45 | application/json: 46 | schema: 47 | $ref: '#/components/schemas/Status' 48 | components: 49 | schemas: 50 | GoogleProtobufAny: 51 | type: object 52 | properties: 53 | '@type': 54 | type: string 55 | description: The type of the serialized message. 56 | additionalProperties: true 57 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 58 | Message: 59 | type: object 60 | properties: 61 | messageId: 62 | type: string 63 | text: 64 | type: string 65 | Status: 66 | type: object 67 | properties: 68 | code: 69 | type: integer 70 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 71 | format: int32 72 | message: 73 | type: string 74 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 75 | details: 76 | type: array 77 | items: 78 | $ref: '#/components/schemas/GoogleProtobufAny' 79 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 80 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 81 | tags: 82 | - name: Messaging 83 | -------------------------------------------------------------------------------- /examples/tests/customparamsexclude/message.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2020 Google LLC. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | // 15 | 16 | syntax = "proto3"; 17 | 18 | package tests.customparams.message.v1; 19 | 20 | import "google/api/annotations.proto"; 21 | import "openapi/annotations.proto"; 22 | 23 | option go_package = "github.com/google/gnostic/apps/protoc-gen-openapi/examples/tests/bodymapping/message/v1;message"; 24 | 25 | option (openapi.file_params) = { headers: [{ name:"FileHeader" }]}; 26 | 27 | service Messaging { 28 | option (openapi.service_params) = { 29 | headers: 30 | [ 31 | { 32 | name:"ServiceHeader", 33 | pattern:"^(.*)$" 34 | description:"This is a service header" 35 | required:true, 36 | } 37 | ], 38 | build_tags: ["postman"] 39 | }; 40 | // Update Message Summary | This function updates a message. 41 | // (-- api-linter: core::0xxx::xxx=disabled 42 | // aip.dev/not-precedent: We need to do this because reasons. --) 43 | rpc UpdateMessage(Message) returns(Message) { 44 | option (google.api.http) = { 45 | patch: "/v1/messages/{message_id}" 46 | body: "text" 47 | }; 48 | option (openapi.method_params) = { 49 | headers: [ 50 | { name:"MethodHeader"} 51 | ] 52 | }; 53 | } 54 | } 55 | message Message { 56 | string message_id = 1; 57 | string text = 2; 58 | } 59 | -------------------------------------------------------------------------------- /examples/tests/customparamsexclude/openapi.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 0.0.1 8 | paths: {} 9 | components: 10 | schemas: {} 11 | tags: 12 | - name: Messaging 13 | -------------------------------------------------------------------------------- /examples/tests/customparamsexclude/openapi_json.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 1.2.3 8 | paths: 9 | /v1/messages/{messageId}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: Update Message Summary 14 | description: This function updates a message. 15 | operationId: Messaging_UpdateMessage 16 | parameters: 17 | - name: messageId 18 | in: path 19 | required: true 20 | schema: 21 | type: string 22 | requestBody: 23 | content: 24 | application/json: 25 | schema: 26 | type: string 27 | required: true 28 | responses: 29 | "200": 30 | description: OK 31 | content: 32 | application/json: 33 | schema: 34 | $ref: '#/components/schemas/Message' 35 | default: 36 | description: Default error response 37 | content: 38 | application/json: 39 | schema: 40 | $ref: '#/components/schemas/Status' 41 | components: 42 | schemas: 43 | GoogleProtobufAny: 44 | type: object 45 | properties: 46 | '@type': 47 | type: string 48 | description: The type of the serialized message. 49 | additionalProperties: true 50 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 51 | Message: 52 | type: object 53 | properties: 54 | messageId: 55 | type: string 56 | text: 57 | type: string 58 | Status: 59 | type: object 60 | properties: 61 | code: 62 | type: integer 63 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 64 | format: int32 65 | message: 66 | type: string 67 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 68 | details: 69 | type: array 70 | items: 71 | $ref: '#/components/schemas/GoogleProtobufAny' 72 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 73 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 74 | tags: 75 | - name: Messaging 76 | -------------------------------------------------------------------------------- /examples/tests/customparamspostmanandpublic/message.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2020 Google LLC. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | // 15 | 16 | syntax = "proto3"; 17 | 18 | package tests.customparams.message.v1; 19 | 20 | import "google/api/annotations.proto"; 21 | import "openapi/annotations.proto"; 22 | 23 | option go_package = "github.com/google/gnostic/apps/protoc-gen-openapi/examples/tests/bodymapping/message/v1;message"; 24 | 25 | option (openapi.file_params) = { headers: [{ name:"FileHeader" }]}; 26 | 27 | service Messaging { 28 | option (openapi.service_params) = { 29 | headers: 30 | [ 31 | { 32 | name:"ServiceHeader", 33 | pattern:"^(.*)$" 34 | description:"This is a service header" 35 | required:true, 36 | } 37 | ], 38 | build_tags: ["postman"] 39 | }; 40 | // Update Message Summary | This function updates a message. 41 | // (-- api-linter: core::0xxx::xxx=disabled 42 | // aip.dev/not-precedent: We need to do this because reasons. --) 43 | rpc UpdateMessage(Message) returns(Message) { 44 | option (google.api.http) = { 45 | patch: "/v1/messages/{message_id}" 46 | body: "text" 47 | }; 48 | } 49 | // Get Message Summary | This function gets a message. 50 | // (-- api-linter: core::0xxx::xxx=disabled 51 | // aip.dev/not-precedent: We need to do this because reasons. --) 52 | rpc GetMessaage(Message) returns(Message) { 53 | option (google.api.http) = { 54 | patch: "/v1/messages/{message_id}" 55 | body: "text" 56 | }; 57 | option (openapi.method_params) = { 58 | build_tags: ["public_docs"] 59 | }; 60 | } 61 | } 62 | message Message { 63 | string message_id = 1; 64 | string text = 2; 65 | } 66 | -------------------------------------------------------------------------------- /examples/tests/customparamspostmanandpublic/openapi.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 0.0.1 8 | paths: 9 | /v1/messages/{message_id}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: Get Message Summary 14 | description: This function gets a message. 15 | operationId: Messaging_GetMessaage 16 | parameters: 17 | - name: message_id 18 | in: path 19 | required: true 20 | schema: 21 | type: string 22 | requestBody: 23 | content: 24 | application/json: 25 | schema: 26 | type: string 27 | required: true 28 | responses: 29 | "200": 30 | description: OK 31 | content: 32 | application/json: 33 | schema: 34 | $ref: '#/components/schemas/Message' 35 | default: 36 | description: Default error response 37 | content: 38 | application/json: 39 | schema: 40 | $ref: '#/components/schemas/Status' 41 | components: 42 | schemas: 43 | GoogleProtobufAny: 44 | type: object 45 | properties: 46 | '@type': 47 | type: string 48 | description: The type of the serialized message. 49 | additionalProperties: true 50 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 51 | Message: 52 | type: object 53 | properties: 54 | message_id: 55 | type: string 56 | text: 57 | type: string 58 | Status: 59 | type: object 60 | properties: 61 | code: 62 | type: integer 63 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 64 | format: int32 65 | message: 66 | type: string 67 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 68 | details: 69 | type: array 70 | items: 71 | $ref: '#/components/schemas/GoogleProtobufAny' 72 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 73 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 74 | tags: 75 | - name: Messaging 76 | -------------------------------------------------------------------------------- /examples/tests/customparamspostmanandpublic/openapi_json.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 1.2.3 8 | paths: 9 | /v1/messages/{messageId}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: Get Message Summary 14 | description: This function gets a message. 15 | operationId: Messaging_GetMessaage 16 | parameters: 17 | - name: messageId 18 | in: path 19 | required: true 20 | schema: 21 | type: string 22 | requestBody: 23 | content: 24 | application/json: 25 | schema: 26 | type: string 27 | required: true 28 | responses: 29 | "200": 30 | description: OK 31 | content: 32 | application/json: 33 | schema: 34 | $ref: '#/components/schemas/Message' 35 | default: 36 | description: Default error response 37 | content: 38 | application/json: 39 | schema: 40 | $ref: '#/components/schemas/Status' 41 | components: 42 | schemas: 43 | GoogleProtobufAny: 44 | type: object 45 | properties: 46 | '@type': 47 | type: string 48 | description: The type of the serialized message. 49 | additionalProperties: true 50 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 51 | Message: 52 | type: object 53 | properties: 54 | messageId: 55 | type: string 56 | text: 57 | type: string 58 | Status: 59 | type: object 60 | properties: 61 | code: 62 | type: integer 63 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 64 | format: int32 65 | message: 66 | type: string 67 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 68 | details: 69 | type: array 70 | items: 71 | $ref: '#/components/schemas/GoogleProtobufAny' 72 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 73 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 74 | tags: 75 | - name: Messaging 76 | -------------------------------------------------------------------------------- /examples/tests/customparamspostmanonly/message.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2020 Google LLC. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | // 15 | 16 | syntax = "proto3"; 17 | 18 | package tests.customparams.message.v1; 19 | 20 | import "google/api/annotations.proto"; 21 | import "openapi/annotations.proto"; 22 | 23 | option go_package = "github.com/google/gnostic/apps/protoc-gen-openapi/examples/tests/bodymapping/message/v1;message"; 24 | 25 | option (openapi.file_params) = { headers: [{ name:"FileHeader" }]}; 26 | 27 | service Messaging { 28 | option (openapi.service_params) = { 29 | headers: 30 | [ 31 | { 32 | name:"ServiceHeader", 33 | pattern:"^(.*)$" 34 | description:"This is a service header" 35 | required:true, 36 | } 37 | ], 38 | build_tags: ["postman"] 39 | }; 40 | // Update Message Summary | This function updates a message. 41 | // (-- api-linter: core::0xxx::xxx=disabled 42 | // aip.dev/not-precedent: We need to do this because reasons. --) 43 | rpc UpdateMessage(Message) returns(Message) { 44 | option (google.api.http) = { 45 | patch: "/v1/messages/{message_id}" 46 | body: "text" 47 | }; 48 | } 49 | } 50 | message Message { 51 | string message_id = 1; 52 | string text = 2; 53 | } 54 | -------------------------------------------------------------------------------- /examples/tests/customparamspostmanonly/openapi.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 0.0.1 8 | paths: 9 | /v1/messages/{message_id}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: Update Message Summary 14 | description: This function updates a message. 15 | operationId: Messaging_UpdateMessage 16 | parameters: 17 | - name: message_id 18 | in: path 19 | required: true 20 | schema: 21 | type: string 22 | - name: ServiceHeader 23 | in: header 24 | description: This is a service header 25 | required: true 26 | schema: 27 | pattern: ^(.*)$ 28 | type: string 29 | requestBody: 30 | content: 31 | application/json: 32 | schema: 33 | type: string 34 | required: true 35 | responses: 36 | "200": 37 | description: OK 38 | content: 39 | application/json: 40 | schema: 41 | $ref: '#/components/schemas/Message' 42 | default: 43 | description: Default error response 44 | content: 45 | application/json: 46 | schema: 47 | $ref: '#/components/schemas/Status' 48 | components: 49 | schemas: 50 | GoogleProtobufAny: 51 | type: object 52 | properties: 53 | '@type': 54 | type: string 55 | description: The type of the serialized message. 56 | additionalProperties: true 57 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 58 | Message: 59 | type: object 60 | properties: 61 | message_id: 62 | type: string 63 | text: 64 | type: string 65 | Status: 66 | type: object 67 | properties: 68 | code: 69 | type: integer 70 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 71 | format: int32 72 | message: 73 | type: string 74 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 75 | details: 76 | type: array 77 | items: 78 | $ref: '#/components/schemas/GoogleProtobufAny' 79 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 80 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 81 | tags: 82 | - name: Messaging 83 | -------------------------------------------------------------------------------- /examples/tests/customparamspostmanonly/openapi_json.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 1.2.3 8 | paths: 9 | /v1/messages/{messageId}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: Update Message Summary 14 | description: This function updates a message. 15 | operationId: Messaging_UpdateMessage 16 | parameters: 17 | - name: messageId 18 | in: path 19 | required: true 20 | schema: 21 | type: string 22 | requestBody: 23 | content: 24 | application/json: 25 | schema: 26 | type: string 27 | required: true 28 | responses: 29 | "200": 30 | description: OK 31 | content: 32 | application/json: 33 | schema: 34 | $ref: '#/components/schemas/Message' 35 | default: 36 | description: Default error response 37 | content: 38 | application/json: 39 | schema: 40 | $ref: '#/components/schemas/Status' 41 | components: 42 | schemas: 43 | GoogleProtobufAny: 44 | type: object 45 | properties: 46 | '@type': 47 | type: string 48 | description: The type of the serialized message. 49 | additionalProperties: true 50 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 51 | Message: 52 | type: object 53 | properties: 54 | messageId: 55 | type: string 56 | text: 57 | type: string 58 | Status: 59 | type: object 60 | properties: 61 | code: 62 | type: integer 63 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 64 | format: int32 65 | message: 66 | type: string 67 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 68 | details: 69 | type: array 70 | items: 71 | $ref: '#/components/schemas/GoogleProtobufAny' 72 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 73 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 74 | tags: 75 | - name: Messaging 76 | -------------------------------------------------------------------------------- /examples/tests/enums/message.proto: -------------------------------------------------------------------------------- 1 | syntax = "proto3"; 2 | 3 | package tests.enums.message.v1; 4 | 5 | import "google/api/annotations.proto"; 6 | import "google/protobuf/wrappers.proto"; 7 | 8 | option go_package = "github.com/kollalabs/protoc-gen-openapi/examples/tests/pathparams/message/v1;message"; 9 | 10 | service Messaging { 11 | rpc GetMessage(GetMessageRequest) returns (Message) { 12 | option (google.api.http) = { 13 | get : "/v1/messages/{message_id}" 14 | }; 15 | } 16 | } 17 | 18 | message GetMessageRequest { 19 | string message_id = 1; 20 | } 21 | 22 | message Message { 23 | string message_id = 1; 24 | string user_id = 2; 25 | google.protobuf.StringValue content = 3; 26 | google.protobuf.BoolValue allowed = 4; 27 | 28 | enum Status { 29 | // Default 30 | STATUS_UNSPECIFIED = 0; 31 | // Approved 32 | APPROVED = 1; 33 | // Pending 34 | PENDING = 2; 35 | } 36 | 37 | Status status = 5; 38 | } -------------------------------------------------------------------------------- /examples/tests/enums/openapi.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 0.0.1 8 | paths: 9 | /v1/messages/{message_id}: 10 | get: 11 | tags: 12 | - Messaging 13 | summary: GetMessage 14 | operationId: Messaging_GetMessage 15 | parameters: 16 | - name: message_id 17 | in: path 18 | required: true 19 | schema: 20 | type: string 21 | responses: 22 | "200": 23 | description: OK 24 | content: 25 | application/json: 26 | schema: 27 | $ref: '#/components/schemas/Message' 28 | default: 29 | description: Default error response 30 | content: 31 | application/json: 32 | schema: 33 | $ref: '#/components/schemas/Status' 34 | components: 35 | schemas: 36 | GoogleProtobufAny: 37 | type: object 38 | properties: 39 | '@type': 40 | type: string 41 | description: The type of the serialized message. 42 | additionalProperties: true 43 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 44 | Message: 45 | type: object 46 | properties: 47 | message_id: 48 | type: string 49 | user_id: 50 | type: string 51 | content: 52 | nullable: true 53 | type: string 54 | allowed: 55 | nullable: true 56 | type: boolean 57 | status: 58 | enum: 59 | - APPROVED 60 | - PENDING 61 | type: string 62 | format: enum 63 | Status: 64 | type: object 65 | properties: 66 | code: 67 | type: integer 68 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 69 | format: int32 70 | message: 71 | type: string 72 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 73 | details: 74 | type: array 75 | items: 76 | $ref: '#/components/schemas/GoogleProtobufAny' 77 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 78 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 79 | tags: 80 | - name: Messaging 81 | -------------------------------------------------------------------------------- /examples/tests/enums/openapi_json.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 1.2.3 8 | paths: 9 | /v1/messages/{messageId}: 10 | get: 11 | tags: 12 | - Messaging 13 | summary: GetMessage 14 | operationId: Messaging_GetMessage 15 | parameters: 16 | - name: messageId 17 | in: path 18 | required: true 19 | schema: 20 | type: string 21 | responses: 22 | "200": 23 | description: OK 24 | content: 25 | application/json: 26 | schema: 27 | $ref: '#/components/schemas/Message' 28 | default: 29 | description: Default error response 30 | content: 31 | application/json: 32 | schema: 33 | $ref: '#/components/schemas/Status' 34 | components: 35 | schemas: 36 | GoogleProtobufAny: 37 | type: object 38 | properties: 39 | '@type': 40 | type: string 41 | description: The type of the serialized message. 42 | additionalProperties: true 43 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 44 | Message: 45 | type: object 46 | properties: 47 | messageId: 48 | type: string 49 | userId: 50 | type: string 51 | content: 52 | nullable: true 53 | type: string 54 | allowed: 55 | nullable: true 56 | type: boolean 57 | status: 58 | enum: 59 | - APPROVED 60 | - PENDING 61 | type: string 62 | format: enum 63 | Status: 64 | type: object 65 | properties: 66 | code: 67 | type: integer 68 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 69 | format: int32 70 | message: 71 | type: string 72 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 73 | details: 74 | type: array 75 | items: 76 | $ref: '#/components/schemas/GoogleProtobufAny' 77 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 78 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 79 | tags: 80 | - name: Messaging 81 | -------------------------------------------------------------------------------- /examples/tests/fieldbehaviors/message.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2020 Google LLC. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | // 15 | 16 | syntax = "proto3"; 17 | 18 | package tests.required.message.v1; 19 | 20 | import "google/api/annotations.proto"; 21 | import "google/api/field_behavior.proto"; 22 | 23 | option go_package = "github.com/google/gnostic/apps/protoc-gen-openapi/examples/tests/required/message/v1;message"; 24 | 25 | service Messaging { 26 | rpc UpdateMessage(Message) returns(Message) { 27 | option(google.api.http) = { 28 | patch: "/v1/messages/{message_id}" 29 | body: "text" 30 | }; 31 | } 32 | } 33 | message Message { 34 | string message_id = 1; 35 | string text = 2 [(google.api.field_behavior) = REQUIRED]; 36 | string outputonly = 3 [(google.api.field_behavior) = OUTPUT_ONLY]; 37 | string inputonly = 4 [(google.api.field_behavior) = INPUT_ONLY]; 38 | } -------------------------------------------------------------------------------- /examples/tests/fieldbehaviors/openapi.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 0.0.1 8 | paths: 9 | /v1/messages/{message_id}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: UpdateMessage 14 | operationId: Messaging_UpdateMessage 15 | parameters: 16 | - name: message_id 17 | in: path 18 | required: true 19 | schema: 20 | type: string 21 | - name: outputonly 22 | in: query 23 | schema: 24 | type: string 25 | - name: inputonly 26 | in: query 27 | schema: 28 | type: string 29 | requestBody: 30 | content: 31 | application/json: 32 | schema: 33 | type: string 34 | required: true 35 | responses: 36 | "200": 37 | description: OK 38 | content: 39 | application/json: 40 | schema: 41 | $ref: '#/components/schemas/Message' 42 | default: 43 | description: Default error response 44 | content: 45 | application/json: 46 | schema: 47 | $ref: '#/components/schemas/Status' 48 | components: 49 | schemas: 50 | GoogleProtobufAny: 51 | type: object 52 | properties: 53 | '@type': 54 | type: string 55 | description: The type of the serialized message. 56 | additionalProperties: true 57 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 58 | Message: 59 | required: 60 | - text 61 | type: object 62 | properties: 63 | message_id: 64 | type: string 65 | text: 66 | type: string 67 | outputonly: 68 | readOnly: true 69 | type: string 70 | inputonly: 71 | writeOnly: true 72 | type: string 73 | Status: 74 | type: object 75 | properties: 76 | code: 77 | type: integer 78 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 79 | format: int32 80 | message: 81 | type: string 82 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 83 | details: 84 | type: array 85 | items: 86 | $ref: '#/components/schemas/GoogleProtobufAny' 87 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 88 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 89 | tags: 90 | - name: Messaging 91 | -------------------------------------------------------------------------------- /examples/tests/fieldbehaviors/openapi_json.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 1.2.3 8 | paths: 9 | /v1/messages/{messageId}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: UpdateMessage 14 | operationId: Messaging_UpdateMessage 15 | parameters: 16 | - name: messageId 17 | in: path 18 | required: true 19 | schema: 20 | type: string 21 | - name: outputonly 22 | in: query 23 | schema: 24 | type: string 25 | - name: inputonly 26 | in: query 27 | schema: 28 | type: string 29 | requestBody: 30 | content: 31 | application/json: 32 | schema: 33 | type: string 34 | required: true 35 | responses: 36 | "200": 37 | description: OK 38 | content: 39 | application/json: 40 | schema: 41 | $ref: '#/components/schemas/Message' 42 | default: 43 | description: Default error response 44 | content: 45 | application/json: 46 | schema: 47 | $ref: '#/components/schemas/Status' 48 | components: 49 | schemas: 50 | GoogleProtobufAny: 51 | type: object 52 | properties: 53 | '@type': 54 | type: string 55 | description: The type of the serialized message. 56 | additionalProperties: true 57 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 58 | Message: 59 | required: 60 | - text 61 | type: object 62 | properties: 63 | messageId: 64 | type: string 65 | text: 66 | type: string 67 | outputonly: 68 | readOnly: true 69 | type: string 70 | inputonly: 71 | writeOnly: true 72 | type: string 73 | Status: 74 | type: object 75 | properties: 76 | code: 77 | type: integer 78 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 79 | format: int32 80 | message: 81 | type: string 82 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 83 | details: 84 | type: array 85 | items: 86 | $ref: '#/components/schemas/GoogleProtobufAny' 87 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 88 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 89 | tags: 90 | - name: Messaging 91 | -------------------------------------------------------------------------------- /examples/tests/jsonoptions/message.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2020 Google LLC. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | // 15 | 16 | syntax = "proto3"; 17 | 18 | package tests.jsonnames.message.v1; 19 | 20 | import "google/api/annotations.proto"; 21 | 22 | option go_package = "github.com/google/gnostic/apps/protoc-gen-openapi/examples/tests/jsonnames/message/v1;message"; 23 | 24 | // Messaging service 25 | service Messaging { 26 | rpc CreateMessage(Message) returns (Message) { 27 | option (google.api.http) = { 28 | post : "/v1/messages/{message_id}" 29 | body : "body_text" 30 | }; 31 | } 32 | rpc UpdateMessage(Message2) returns (Message2) { 33 | option (google.api.http) = { 34 | patch : "/v1/messages/{message_id}" 35 | body : "body_text" 36 | }; 37 | } 38 | } 39 | message Message { 40 | string message_id = 1; 41 | string body_text = 2; 42 | string not_used = 3; 43 | } 44 | message Message2 { 45 | string message_id = 1 [ json_name = "message_id" ]; 46 | string body_text = 2 [ json_name = "body_text" ]; 47 | string not_used = 3 [ json_name = "not_used" ]; 48 | } 49 | -------------------------------------------------------------------------------- /examples/tests/jsonoptions/openapi.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | description: Messaging service 8 | version: 0.0.1 9 | paths: 10 | /v1/messages/{message_id}: 11 | post: 12 | tags: 13 | - Messaging 14 | summary: CreateMessage 15 | operationId: Messaging_CreateMessage 16 | parameters: 17 | - name: message_id 18 | in: path 19 | required: true 20 | schema: 21 | type: string 22 | - name: not_used 23 | in: query 24 | schema: 25 | type: string 26 | requestBody: 27 | content: 28 | application/json: 29 | schema: 30 | type: string 31 | required: true 32 | responses: 33 | "200": 34 | description: OK 35 | content: 36 | application/json: 37 | schema: 38 | $ref: '#/components/schemas/Message' 39 | default: 40 | description: Default error response 41 | content: 42 | application/json: 43 | schema: 44 | $ref: '#/components/schemas/Status' 45 | patch: 46 | tags: 47 | - Messaging 48 | summary: UpdateMessage 49 | operationId: Messaging_UpdateMessage 50 | parameters: 51 | - name: message_id 52 | in: path 53 | required: true 54 | schema: 55 | type: string 56 | - name: not_used 57 | in: query 58 | schema: 59 | type: string 60 | requestBody: 61 | content: 62 | application/json: 63 | schema: 64 | type: string 65 | required: true 66 | responses: 67 | "200": 68 | description: OK 69 | content: 70 | application/json: 71 | schema: 72 | $ref: '#/components/schemas/Message2' 73 | default: 74 | description: Default error response 75 | content: 76 | application/json: 77 | schema: 78 | $ref: '#/components/schemas/Status' 79 | components: 80 | schemas: 81 | GoogleProtobufAny: 82 | type: object 83 | properties: 84 | '@type': 85 | type: string 86 | description: The type of the serialized message. 87 | additionalProperties: true 88 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 89 | Message: 90 | type: object 91 | properties: 92 | message_id: 93 | type: string 94 | body_text: 95 | type: string 96 | not_used: 97 | type: string 98 | Message2: 99 | type: object 100 | properties: 101 | message_id: 102 | type: string 103 | body_text: 104 | type: string 105 | not_used: 106 | type: string 107 | Status: 108 | type: object 109 | properties: 110 | code: 111 | type: integer 112 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 113 | format: int32 114 | message: 115 | type: string 116 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 117 | details: 118 | type: array 119 | items: 120 | $ref: '#/components/schemas/GoogleProtobufAny' 121 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 122 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 123 | tags: 124 | - name: Messaging 125 | -------------------------------------------------------------------------------- /examples/tests/jsonoptions/openapi_json.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | description: Messaging service 8 | version: 1.2.3 9 | paths: 10 | /v1/messages/{messageId}: 11 | post: 12 | tags: 13 | - Messaging 14 | summary: CreateMessage 15 | operationId: Messaging_CreateMessage 16 | parameters: 17 | - name: messageId 18 | in: path 19 | required: true 20 | schema: 21 | type: string 22 | - name: notUsed 23 | in: query 24 | schema: 25 | type: string 26 | requestBody: 27 | content: 28 | application/json: 29 | schema: 30 | type: string 31 | required: true 32 | responses: 33 | "200": 34 | description: OK 35 | content: 36 | application/json: 37 | schema: 38 | $ref: '#/components/schemas/Message' 39 | default: 40 | description: Default error response 41 | content: 42 | application/json: 43 | schema: 44 | $ref: '#/components/schemas/Status' 45 | /v1/messages/{message_id}: 46 | patch: 47 | tags: 48 | - Messaging 49 | summary: UpdateMessage 50 | operationId: Messaging_UpdateMessage 51 | parameters: 52 | - name: message_id 53 | in: path 54 | required: true 55 | schema: 56 | type: string 57 | - name: not_used 58 | in: query 59 | schema: 60 | type: string 61 | requestBody: 62 | content: 63 | application/json: 64 | schema: 65 | type: string 66 | required: true 67 | responses: 68 | "200": 69 | description: OK 70 | content: 71 | application/json: 72 | schema: 73 | $ref: '#/components/schemas/Message2' 74 | default: 75 | description: Default error response 76 | content: 77 | application/json: 78 | schema: 79 | $ref: '#/components/schemas/Status' 80 | components: 81 | schemas: 82 | GoogleProtobufAny: 83 | type: object 84 | properties: 85 | '@type': 86 | type: string 87 | description: The type of the serialized message. 88 | additionalProperties: true 89 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 90 | Message: 91 | type: object 92 | properties: 93 | messageId: 94 | type: string 95 | bodyText: 96 | type: string 97 | notUsed: 98 | type: string 99 | Message2: 100 | type: object 101 | properties: 102 | message_id: 103 | type: string 104 | body_text: 105 | type: string 106 | not_used: 107 | type: string 108 | Status: 109 | type: object 110 | properties: 111 | code: 112 | type: integer 113 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 114 | format: int32 115 | message: 116 | type: string 117 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 118 | details: 119 | type: array 120 | items: 121 | $ref: '#/components/schemas/GoogleProtobufAny' 122 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 123 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 124 | tags: 125 | - name: Messaging 126 | -------------------------------------------------------------------------------- /examples/tests/mapfields/message.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2021 Google LLC. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | // 15 | 16 | syntax = "proto3"; 17 | 18 | package tests.mapfields.message.v1; 19 | 20 | import "google/api/annotations.proto"; 21 | import "google/protobuf/struct.proto"; 22 | 23 | option go_package = "github.com/google/gnostic/apps/protoc-gen-openapi/examples/tests/mapfields/message/v1;message"; 24 | 25 | service Messaging { 26 | rpc UpdateMessage(Message) returns(Message) { 27 | option(google.api.http) = { 28 | patch: "/v1/messages/{message_id}" 29 | body: "*" 30 | }; 31 | } 32 | } 33 | 34 | message AnotherMessage { 35 | int64 id = 1; 36 | string label = 2; 37 | } 38 | 39 | message Message { 40 | message SubMessage { 41 | int64 id = 1; 42 | string label = 2; 43 | } 44 | string message_id = 1; 45 | AnotherMessage another_message = 2; 46 | SubMessage sub_message = 3; 47 | repeated string string_list = 4; 48 | repeated SubMessage sub_message_list = 5; 49 | repeated google.protobuf.Struct object_list = 6; 50 | map strings_map = 7; 51 | map sub_messages_map = 8; 52 | map objects_map = 9; 53 | } 54 | -------------------------------------------------------------------------------- /examples/tests/mapfields/openapi.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 0.0.1 8 | paths: 9 | /v1/messages/{message_id}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: UpdateMessage 14 | operationId: Messaging_UpdateMessage 15 | parameters: 16 | - name: message_id 17 | in: path 18 | required: true 19 | schema: 20 | type: string 21 | requestBody: 22 | content: 23 | application/json: 24 | schema: 25 | $ref: '#/components/schemas/Message' 26 | required: true 27 | responses: 28 | "200": 29 | description: OK 30 | content: 31 | application/json: 32 | schema: 33 | $ref: '#/components/schemas/Message' 34 | default: 35 | description: Default error response 36 | content: 37 | application/json: 38 | schema: 39 | $ref: '#/components/schemas/Status' 40 | components: 41 | schemas: 42 | AnotherMessage: 43 | type: object 44 | properties: 45 | id: 46 | type: integer 47 | format: int64 48 | label: 49 | type: string 50 | GoogleProtobufAny: 51 | type: object 52 | properties: 53 | '@type': 54 | type: string 55 | description: The type of the serialized message. 56 | additionalProperties: true 57 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 58 | Message: 59 | type: object 60 | properties: 61 | message_id: 62 | type: string 63 | another_message: 64 | $ref: '#/components/schemas/AnotherMessage' 65 | sub_message: 66 | $ref: '#/components/schemas/Message_SubMessage' 67 | string_list: 68 | type: array 69 | items: 70 | type: string 71 | sub_message_list: 72 | type: array 73 | items: 74 | $ref: '#/components/schemas/Message_SubMessage' 75 | object_list: 76 | type: array 77 | items: 78 | type: object 79 | strings_map: 80 | type: object 81 | additionalProperties: 82 | type: string 83 | sub_messages_map: 84 | type: object 85 | additionalProperties: 86 | $ref: '#/components/schemas/Message_SubMessage' 87 | objects_map: 88 | type: object 89 | additionalProperties: 90 | type: object 91 | Message_SubMessage: 92 | type: object 93 | properties: 94 | id: 95 | type: integer 96 | format: int64 97 | label: 98 | type: string 99 | Status: 100 | type: object 101 | properties: 102 | code: 103 | type: integer 104 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 105 | format: int32 106 | message: 107 | type: string 108 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 109 | details: 110 | type: array 111 | items: 112 | $ref: '#/components/schemas/GoogleProtobufAny' 113 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 114 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 115 | tags: 116 | - name: Messaging 117 | -------------------------------------------------------------------------------- /examples/tests/mapfields/openapi_json.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 1.2.3 8 | paths: 9 | /v1/messages/{messageId}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: UpdateMessage 14 | operationId: Messaging_UpdateMessage 15 | parameters: 16 | - name: messageId 17 | in: path 18 | required: true 19 | schema: 20 | type: string 21 | requestBody: 22 | content: 23 | application/json: 24 | schema: 25 | $ref: '#/components/schemas/Message' 26 | required: true 27 | responses: 28 | "200": 29 | description: OK 30 | content: 31 | application/json: 32 | schema: 33 | $ref: '#/components/schemas/Message' 34 | default: 35 | description: Default error response 36 | content: 37 | application/json: 38 | schema: 39 | $ref: '#/components/schemas/Status' 40 | components: 41 | schemas: 42 | AnotherMessage: 43 | type: object 44 | properties: 45 | id: 46 | type: integer 47 | format: int64 48 | label: 49 | type: string 50 | GoogleProtobufAny: 51 | type: object 52 | properties: 53 | '@type': 54 | type: string 55 | description: The type of the serialized message. 56 | additionalProperties: true 57 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 58 | Message: 59 | type: object 60 | properties: 61 | messageId: 62 | type: string 63 | anotherMessage: 64 | $ref: '#/components/schemas/AnotherMessage' 65 | subMessage: 66 | $ref: '#/components/schemas/Message_SubMessage' 67 | stringList: 68 | type: array 69 | items: 70 | type: string 71 | subMessageList: 72 | type: array 73 | items: 74 | $ref: '#/components/schemas/Message_SubMessage' 75 | objectList: 76 | type: array 77 | items: 78 | type: object 79 | stringsMap: 80 | type: object 81 | additionalProperties: 82 | type: string 83 | subMessagesMap: 84 | type: object 85 | additionalProperties: 86 | $ref: '#/components/schemas/Message_SubMessage' 87 | objectsMap: 88 | type: object 89 | additionalProperties: 90 | type: object 91 | Message_SubMessage: 92 | type: object 93 | properties: 94 | id: 95 | type: integer 96 | format: int64 97 | label: 98 | type: string 99 | Status: 100 | type: object 101 | properties: 102 | code: 103 | type: integer 104 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 105 | format: int32 106 | message: 107 | type: string 108 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 109 | details: 110 | type: array 111 | items: 112 | $ref: '#/components/schemas/GoogleProtobufAny' 113 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 114 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 115 | tags: 116 | - name: Messaging 117 | -------------------------------------------------------------------------------- /examples/tests/messagenamepattern/message.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2020 Google LLC. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | // 15 | 16 | syntax = "proto3"; 17 | 18 | package tests.bodymappying.message.v1; 19 | 20 | import "google/api/annotations.proto"; 21 | import "google/api/resource.proto"; 22 | 23 | option go_package = "github.com/google/gnostic/apps/protoc-gen-openapi/examples/tests/bodymapping/message/v1;message"; 24 | 25 | service Messaging { 26 | // Update Message Summary | This function updates a message. 27 | rpc UpdateMessage(Message) returns(Message) { 28 | option(google.api.http) = { 29 | patch: "/v1/messages/{message_id}" 30 | body: "text" 31 | }; 32 | } 33 | } 34 | message Message { 35 | option (google.api.resource) = { 36 | type: "library-example.googleapis.com/Message", 37 | pattern: "conversation/{conversation_id}/message/{message_id}" 38 | }; 39 | string name = 1; 40 | string message_id = 2; 41 | string text = 3; 42 | } 43 | -------------------------------------------------------------------------------- /examples/tests/messagenamepattern/openapi.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 0.0.1 8 | paths: 9 | /v1/messages/{message_id}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: Update Message Summary 14 | description: This function updates a message. 15 | operationId: Messaging_UpdateMessage 16 | parameters: 17 | - name: message_id 18 | in: path 19 | required: true 20 | schema: 21 | type: string 22 | - name: name 23 | in: query 24 | schema: 25 | type: string 26 | requestBody: 27 | content: 28 | application/json: 29 | schema: 30 | type: string 31 | required: true 32 | responses: 33 | "200": 34 | description: OK 35 | content: 36 | application/json: 37 | schema: 38 | $ref: '#/components/schemas/Message' 39 | default: 40 | description: Default error response 41 | content: 42 | application/json: 43 | schema: 44 | $ref: '#/components/schemas/Status' 45 | components: 46 | schemas: 47 | GoogleProtobufAny: 48 | type: object 49 | properties: 50 | '@type': 51 | type: string 52 | description: The type of the serialized message. 53 | additionalProperties: true 54 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 55 | Message: 56 | type: object 57 | properties: 58 | name: 59 | pattern: ^conversation/[a-z2-7]{26}/message/[a-z2-7]{26}$ 60 | type: string 61 | message_id: 62 | type: string 63 | text: 64 | type: string 65 | Status: 66 | type: object 67 | properties: 68 | code: 69 | type: integer 70 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 71 | format: int32 72 | message: 73 | type: string 74 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 75 | details: 76 | type: array 77 | items: 78 | $ref: '#/components/schemas/GoogleProtobufAny' 79 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 80 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 81 | tags: 82 | - name: Messaging 83 | -------------------------------------------------------------------------------- /examples/tests/messagenamepattern/openapi_json.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 1.2.3 8 | paths: 9 | /v1/messages/{messageId}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: Update Message Summary 14 | description: This function updates a message. 15 | operationId: Messaging_UpdateMessage 16 | parameters: 17 | - name: messageId 18 | in: path 19 | required: true 20 | schema: 21 | type: string 22 | - name: name 23 | in: query 24 | schema: 25 | type: string 26 | requestBody: 27 | content: 28 | application/json: 29 | schema: 30 | type: string 31 | required: true 32 | responses: 33 | "200": 34 | description: OK 35 | content: 36 | application/json: 37 | schema: 38 | $ref: '#/components/schemas/Message' 39 | default: 40 | description: Default error response 41 | content: 42 | application/json: 43 | schema: 44 | $ref: '#/components/schemas/Status' 45 | components: 46 | schemas: 47 | GoogleProtobufAny: 48 | type: object 49 | properties: 50 | '@type': 51 | type: string 52 | description: The type of the serialized message. 53 | additionalProperties: true 54 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 55 | Message: 56 | type: object 57 | properties: 58 | name: 59 | pattern: ^conversation/[a-z2-7]{26}/message/[a-z2-7]{26}$ 60 | type: string 61 | messageId: 62 | type: string 63 | text: 64 | type: string 65 | Status: 66 | type: object 67 | properties: 68 | code: 69 | type: integer 70 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 71 | format: int32 72 | message: 73 | type: string 74 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 75 | details: 76 | type: array 77 | items: 78 | $ref: '#/components/schemas/GoogleProtobufAny' 79 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 80 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 81 | tags: 82 | - name: Messaging 83 | -------------------------------------------------------------------------------- /examples/tests/noannotations/message.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2021 Google LLC. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | // 15 | 16 | syntax = "proto3"; 17 | 18 | package tests.mapfields.message.v1; 19 | 20 | import "google/api/annotations.proto"; 21 | import "google/protobuf/struct.proto"; 22 | 23 | option go_package = "github.com/google/gnostic/apps/protoc-gen-openapi/examples/tests/noannotations/message/v1;message"; 24 | 25 | service Messaging1 { 26 | rpc UpdateMessage(Message) returns(Message) { 27 | option(google.api.http) = { 28 | patch: "/v1/messages/{message_id}" 29 | body: "*" 30 | }; 31 | } 32 | } 33 | 34 | service Messaging2 { 35 | rpc UpdateMessage(Message) returns (Message) {} 36 | } 37 | 38 | message Message { 39 | int64 id = 1; 40 | string label = 2; 41 | } 42 | -------------------------------------------------------------------------------- /examples/tests/noannotations/openapi.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging1 API 7 | version: 0.0.1 8 | paths: 9 | /v1/messages/{message_id}: 10 | patch: 11 | tags: 12 | - Messaging1 13 | summary: UpdateMessage 14 | operationId: Messaging1_UpdateMessage 15 | parameters: 16 | - name: message_id 17 | in: path 18 | required: true 19 | schema: 20 | type: string 21 | requestBody: 22 | content: 23 | application/json: 24 | schema: 25 | $ref: '#/components/schemas/Message' 26 | required: true 27 | responses: 28 | "200": 29 | description: OK 30 | content: 31 | application/json: 32 | schema: 33 | $ref: '#/components/schemas/Message' 34 | default: 35 | description: Default error response 36 | content: 37 | application/json: 38 | schema: 39 | $ref: '#/components/schemas/Status' 40 | components: 41 | schemas: 42 | GoogleProtobufAny: 43 | type: object 44 | properties: 45 | '@type': 46 | type: string 47 | description: The type of the serialized message. 48 | additionalProperties: true 49 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 50 | Message: 51 | type: object 52 | properties: 53 | id: 54 | type: integer 55 | format: int64 56 | label: 57 | type: string 58 | Status: 59 | type: object 60 | properties: 61 | code: 62 | type: integer 63 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 64 | format: int32 65 | message: 66 | type: string 67 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 68 | details: 69 | type: array 70 | items: 71 | $ref: '#/components/schemas/GoogleProtobufAny' 72 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 73 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 74 | tags: 75 | - name: Messaging1 76 | -------------------------------------------------------------------------------- /examples/tests/noannotations/openapi_json.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging1 API 7 | version: 1.2.3 8 | paths: 9 | /v1/messages/{message_id}: 10 | patch: 11 | tags: 12 | - Messaging1 13 | summary: UpdateMessage 14 | operationId: Messaging1_UpdateMessage 15 | parameters: 16 | - name: message_id 17 | in: path 18 | required: true 19 | schema: 20 | type: string 21 | requestBody: 22 | content: 23 | application/json: 24 | schema: 25 | $ref: '#/components/schemas/Message' 26 | required: true 27 | responses: 28 | "200": 29 | description: OK 30 | content: 31 | application/json: 32 | schema: 33 | $ref: '#/components/schemas/Message' 34 | default: 35 | description: Default error response 36 | content: 37 | application/json: 38 | schema: 39 | $ref: '#/components/schemas/Status' 40 | components: 41 | schemas: 42 | GoogleProtobufAny: 43 | type: object 44 | properties: 45 | '@type': 46 | type: string 47 | description: The type of the serialized message. 48 | additionalProperties: true 49 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 50 | Message: 51 | type: object 52 | properties: 53 | id: 54 | type: integer 55 | format: int64 56 | label: 57 | type: string 58 | Status: 59 | type: object 60 | properties: 61 | code: 62 | type: integer 63 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 64 | format: int32 65 | message: 66 | type: string 67 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 68 | details: 69 | type: array 70 | items: 71 | $ref: '#/components/schemas/GoogleProtobufAny' 72 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 73 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 74 | tags: 75 | - name: Messaging1 76 | -------------------------------------------------------------------------------- /examples/tests/pathparams/message.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2021 Google LLC. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | // 15 | 16 | syntax = "proto3"; 17 | 18 | package tests.pathparams.message.v1; 19 | 20 | import "google/api/annotations.proto"; 21 | 22 | option go_package = "github.com/google/gnostic/apps/protoc-gen-openapi/examples/tests/pathparams/message/v1;message"; 23 | 24 | service Messaging { 25 | rpc GetMessage(GetMessageRequest) returns (Message) { 26 | option (google.api.http) = { 27 | get : "/v1/messages/{message_id}" 28 | }; 29 | } 30 | 31 | rpc GetUserMessage(GetMessageRequest) returns (Message) { 32 | option (google.api.http) = { 33 | get : "/v1/users/{user_id}/messages/{message_id}" 34 | }; 35 | } 36 | 37 | rpc CreateMessage(Message) returns (Message) { 38 | option (google.api.http) = { 39 | post : "/v1/messages/{message_id}" 40 | body : "*" 41 | }; 42 | } 43 | } 44 | message GetMessageRequest { 45 | string message_id = 1; 46 | string user_id = 2; 47 | } 48 | 49 | message Message { 50 | string message_id = 1; 51 | string user_id = 2; 52 | string content = 3; 53 | } -------------------------------------------------------------------------------- /examples/tests/pathparams/openapi.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 0.0.1 8 | paths: 9 | /v1/messages/{message_id}: 10 | get: 11 | tags: 12 | - Messaging 13 | summary: GetMessage 14 | operationId: Messaging_GetMessage 15 | parameters: 16 | - name: message_id 17 | in: path 18 | required: true 19 | schema: 20 | type: string 21 | - name: user_id 22 | in: query 23 | schema: 24 | type: string 25 | responses: 26 | "200": 27 | description: OK 28 | content: 29 | application/json: 30 | schema: 31 | $ref: '#/components/schemas/Message' 32 | default: 33 | description: Default error response 34 | content: 35 | application/json: 36 | schema: 37 | $ref: '#/components/schemas/Status' 38 | post: 39 | tags: 40 | - Messaging 41 | summary: CreateMessage 42 | operationId: Messaging_CreateMessage 43 | parameters: 44 | - name: message_id 45 | in: path 46 | required: true 47 | schema: 48 | type: string 49 | requestBody: 50 | content: 51 | application/json: 52 | schema: 53 | $ref: '#/components/schemas/Message' 54 | required: true 55 | responses: 56 | "200": 57 | description: OK 58 | content: 59 | application/json: 60 | schema: 61 | $ref: '#/components/schemas/Message' 62 | default: 63 | description: Default error response 64 | content: 65 | application/json: 66 | schema: 67 | $ref: '#/components/schemas/Status' 68 | /v1/users/{user_id}/messages/{message_id}: 69 | get: 70 | tags: 71 | - Messaging 72 | summary: GetUserMessage 73 | operationId: Messaging_GetUserMessage 74 | parameters: 75 | - name: user_id 76 | in: path 77 | required: true 78 | schema: 79 | type: string 80 | - name: message_id 81 | in: path 82 | required: true 83 | schema: 84 | type: string 85 | responses: 86 | "200": 87 | description: OK 88 | content: 89 | application/json: 90 | schema: 91 | $ref: '#/components/schemas/Message' 92 | default: 93 | description: Default error response 94 | content: 95 | application/json: 96 | schema: 97 | $ref: '#/components/schemas/Status' 98 | components: 99 | schemas: 100 | GoogleProtobufAny: 101 | type: object 102 | properties: 103 | '@type': 104 | type: string 105 | description: The type of the serialized message. 106 | additionalProperties: true 107 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 108 | Message: 109 | type: object 110 | properties: 111 | message_id: 112 | type: string 113 | user_id: 114 | type: string 115 | content: 116 | type: string 117 | Status: 118 | type: object 119 | properties: 120 | code: 121 | type: integer 122 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 123 | format: int32 124 | message: 125 | type: string 126 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 127 | details: 128 | type: array 129 | items: 130 | $ref: '#/components/schemas/GoogleProtobufAny' 131 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 132 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 133 | tags: 134 | - name: Messaging 135 | -------------------------------------------------------------------------------- /examples/tests/pathparams/openapi_json.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 1.2.3 8 | paths: 9 | /v1/messages/{messageId}: 10 | get: 11 | tags: 12 | - Messaging 13 | summary: GetMessage 14 | operationId: Messaging_GetMessage 15 | parameters: 16 | - name: messageId 17 | in: path 18 | required: true 19 | schema: 20 | type: string 21 | - name: userId 22 | in: query 23 | schema: 24 | type: string 25 | responses: 26 | "200": 27 | description: OK 28 | content: 29 | application/json: 30 | schema: 31 | $ref: '#/components/schemas/Message' 32 | default: 33 | description: Default error response 34 | content: 35 | application/json: 36 | schema: 37 | $ref: '#/components/schemas/Status' 38 | post: 39 | tags: 40 | - Messaging 41 | summary: CreateMessage 42 | operationId: Messaging_CreateMessage 43 | parameters: 44 | - name: messageId 45 | in: path 46 | required: true 47 | schema: 48 | type: string 49 | requestBody: 50 | content: 51 | application/json: 52 | schema: 53 | $ref: '#/components/schemas/Message' 54 | required: true 55 | responses: 56 | "200": 57 | description: OK 58 | content: 59 | application/json: 60 | schema: 61 | $ref: '#/components/schemas/Message' 62 | default: 63 | description: Default error response 64 | content: 65 | application/json: 66 | schema: 67 | $ref: '#/components/schemas/Status' 68 | /v1/users/{userId}/messages/{messageId}: 69 | get: 70 | tags: 71 | - Messaging 72 | summary: GetUserMessage 73 | operationId: Messaging_GetUserMessage 74 | parameters: 75 | - name: userId 76 | in: path 77 | required: true 78 | schema: 79 | type: string 80 | - name: messageId 81 | in: path 82 | required: true 83 | schema: 84 | type: string 85 | responses: 86 | "200": 87 | description: OK 88 | content: 89 | application/json: 90 | schema: 91 | $ref: '#/components/schemas/Message' 92 | default: 93 | description: Default error response 94 | content: 95 | application/json: 96 | schema: 97 | $ref: '#/components/schemas/Status' 98 | components: 99 | schemas: 100 | GoogleProtobufAny: 101 | type: object 102 | properties: 103 | '@type': 104 | type: string 105 | description: The type of the serialized message. 106 | additionalProperties: true 107 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 108 | Message: 109 | type: object 110 | properties: 111 | messageId: 112 | type: string 113 | userId: 114 | type: string 115 | content: 116 | type: string 117 | Status: 118 | type: object 119 | properties: 120 | code: 121 | type: integer 122 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 123 | format: int32 124 | message: 125 | type: string 126 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 127 | details: 128 | type: array 129 | items: 130 | $ref: '#/components/schemas/GoogleProtobufAny' 131 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 132 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 133 | tags: 134 | - name: Messaging 135 | -------------------------------------------------------------------------------- /examples/tests/protobuftypes/message.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2021 Google LLC. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | // 15 | 16 | syntax = "proto3"; 17 | 18 | package tests.protobuftypes.message.v1; 19 | 20 | import "google/api/annotations.proto"; 21 | import "google/api/client.proto"; 22 | import "google/api/httpbody.proto"; 23 | import "google/protobuf/duration.proto"; 24 | import "google/protobuf/empty.proto"; 25 | import "google/protobuf/struct.proto"; 26 | import "google/protobuf/timestamp.proto"; 27 | 28 | option go_package = "github.com/google/gnostic/apps/protoc-gen-openapi/examples/tests/protobuftypes/message/v1;message"; 29 | 30 | service Messaging { 31 | option (google.api.default_host) = "foo.googleapi.com"; 32 | rpc CreateMessage(Message) returns (Message) { 33 | option (google.api.http) = { 34 | post : "/v1/messages/{message_id}" 35 | body : "*" 36 | }; 37 | } 38 | rpc CreateMessagesFromCSV(google.api.HttpBody) returns (google.api.HttpBody) { 39 | option (google.api.http) = { 40 | post : "/v1/messages:csv" 41 | body : "*" 42 | }; 43 | } 44 | rpc ListMessages(google.protobuf.Empty) returns (google.protobuf.Value) { 45 | option (google.api.http) = { 46 | get : "/v1/messages" 47 | }; 48 | } 49 | // OpenAPI does not allow requestBody in GET operations. 50 | // But it should not convert it to query params either. 51 | rpc ListMessagesCSV(google.api.HttpBody) returns (google.api.HttpBody) { 52 | option (google.api.http) = { 53 | get : "/v1/messages:csv" 54 | }; 55 | } 56 | rpc GetMessage(Message) returns (Message) { 57 | option (google.api.http) = { 58 | get : "/v1/messages/{message_id}" 59 | }; 60 | } 61 | rpc UpdateMessage(Message) returns (google.protobuf.Struct) { 62 | option (google.api.http) = { 63 | patch : "/v1/messages/{message_id}" 64 | body : "body" 65 | }; 66 | } 67 | } 68 | 69 | message RecursiveParent { 70 | int32 parent_id = 1; 71 | RecursiveChild child = 2; 72 | } 73 | message RecursiveChild { 74 | int32 child_id = 1; 75 | RecursiveParent parent = 2; 76 | } 77 | 78 | message SubMessage { 79 | string message_id = 1; 80 | SubSubMessage sub_sub_message = 2; 81 | } 82 | 83 | message SubSubMessage { 84 | string message_id = 1; 85 | repeated int32 integers = 2; 86 | } 87 | 88 | message Message { 89 | message EmbMessage { string message_id = 1; } 90 | string message_id = 1; 91 | string string_type = 2; 92 | RecursiveParent recursive_type = 3; 93 | EmbMessage embedded_type = 4; 94 | SubMessage sub_type = 5; 95 | repeated string repeated_type = 6; 96 | repeated SubMessage repeated_sub_type = 7; 97 | repeated RecursiveParent repeated_recursive_type = 8; 98 | map map_type = 9; 99 | google.protobuf.Struct body = 10; 100 | repeated google.protobuf.Struct media = 11; 101 | google.protobuf.Empty not_used = 12; 102 | // Description of value 103 | google.protobuf.Value value_type = 13; 104 | // Description of repeated value 105 | repeated google.protobuf.Value repeated_value_type = 14; 106 | // Description of wkt timestamp 107 | google.protobuf.Timestamp timestamp_type = 15; 108 | // Description of wkt duration 109 | google.protobuf.Duration duration_type = 16; 110 | } 111 | -------------------------------------------------------------------------------- /examples/tests/summary/message.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2020 Google LLC. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | // 15 | 16 | syntax = "proto3"; 17 | 18 | package tests.bodymappying.message.v1; 19 | 20 | import "google/api/annotations.proto"; 21 | 22 | option go_package = "github.com/google/gnostic/apps/protoc-gen-openapi/examples/tests/bodymapping/message/v1;message"; 23 | 24 | service Messaging { 25 | // Update Message Summary | This function updates a message. 26 | // (-- api-linter: core::0xxx::xxx=disabled 27 | // aip.dev/not-precedent: We need to do this because reasons. --) 28 | rpc UpdateMessage(Message) returns(Message) { 29 | option(google.api.http) = { 30 | patch: "/v1/messages/{message_id}" 31 | body: "text" 32 | }; 33 | } 34 | } 35 | message Message { 36 | string message_id = 1; 37 | string text = 2; 38 | bytes byte_string = 3; 39 | } 40 | -------------------------------------------------------------------------------- /examples/tests/summary/openapi.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 0.0.1 8 | paths: 9 | /v1/messages/{message_id}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: Update Message Summary 14 | description: This function updates a message. 15 | operationId: Messaging_UpdateMessage 16 | parameters: 17 | - name: message_id 18 | in: path 19 | required: true 20 | schema: 21 | type: string 22 | - name: byte_string 23 | in: query 24 | schema: 25 | type: string 26 | format: byte 27 | requestBody: 28 | content: 29 | application/json: 30 | schema: 31 | type: string 32 | required: true 33 | responses: 34 | "200": 35 | description: OK 36 | content: 37 | application/json: 38 | schema: 39 | $ref: '#/components/schemas/Message' 40 | default: 41 | description: Default error response 42 | content: 43 | application/json: 44 | schema: 45 | $ref: '#/components/schemas/Status' 46 | components: 47 | schemas: 48 | GoogleProtobufAny: 49 | type: object 50 | properties: 51 | '@type': 52 | type: string 53 | description: The type of the serialized message. 54 | additionalProperties: true 55 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 56 | Message: 57 | type: object 58 | properties: 59 | message_id: 60 | type: string 61 | text: 62 | type: string 63 | byte_string: 64 | type: string 65 | format: byte 66 | Status: 67 | type: object 68 | properties: 69 | code: 70 | type: integer 71 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 72 | format: int32 73 | message: 74 | type: string 75 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 76 | details: 77 | type: array 78 | items: 79 | $ref: '#/components/schemas/GoogleProtobufAny' 80 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 81 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 82 | tags: 83 | - name: Messaging 84 | -------------------------------------------------------------------------------- /examples/tests/summary/openapi_json.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 1.2.3 8 | paths: 9 | /v1/messages/{messageId}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: Update Message Summary 14 | description: This function updates a message. 15 | operationId: Messaging_UpdateMessage 16 | parameters: 17 | - name: messageId 18 | in: path 19 | required: true 20 | schema: 21 | type: string 22 | - name: byteString 23 | in: query 24 | schema: 25 | type: string 26 | format: byte 27 | requestBody: 28 | content: 29 | application/json: 30 | schema: 31 | type: string 32 | required: true 33 | responses: 34 | "200": 35 | description: OK 36 | content: 37 | application/json: 38 | schema: 39 | $ref: '#/components/schemas/Message' 40 | default: 41 | description: Default error response 42 | content: 43 | application/json: 44 | schema: 45 | $ref: '#/components/schemas/Status' 46 | components: 47 | schemas: 48 | GoogleProtobufAny: 49 | type: object 50 | properties: 51 | '@type': 52 | type: string 53 | description: The type of the serialized message. 54 | additionalProperties: true 55 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 56 | Message: 57 | type: object 58 | properties: 59 | messageId: 60 | type: string 61 | text: 62 | type: string 63 | byteString: 64 | type: string 65 | format: byte 66 | Status: 67 | type: object 68 | properties: 69 | code: 70 | type: integer 71 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 72 | format: int32 73 | message: 74 | type: string 75 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 76 | details: 77 | type: array 78 | items: 79 | $ref: '#/components/schemas/GoogleProtobufAny' 80 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 81 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 82 | tags: 83 | - name: Messaging 84 | -------------------------------------------------------------------------------- /examples/tests/validate/message.proto: -------------------------------------------------------------------------------- 1 | // Copyright 2020 Google LLC. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | // 15 | 16 | syntax = "proto3"; 17 | 18 | package tests.bodymappying.message.v1; 19 | 20 | import "google/api/annotations.proto"; 21 | import "envoy/validate.proto"; 22 | 23 | option go_package = "github.com/google/gnostic/apps/protoc-gen-openapi/examples/tests/bodymapping/message/v1;message"; 24 | 25 | service Messaging { 26 | // Update Message Summary | This function updates a message. 27 | rpc UpdateMessage(Message) returns(Message) { 28 | option(google.api.http) = { 29 | patch: "/v1/messages/{message_id}" 30 | body: "text" 31 | }; 32 | } 33 | } 34 | message Message { 35 | string message_id = 1; 36 | string text = 2 [ 37 | (validate.rules)= { 38 | string: { 39 | uri:true, 40 | max_len:45, 41 | min_len:1 42 | } 43 | }]; 44 | 45 | int64 mynum = 3 [(validate.rules).int64 = {gte:1, lte:30}]; 46 | 47 | repeated string patterns = 4 [ 48 | (validate.rules).repeated = { 49 | ignore_empty: true, 50 | min_items: 1, 51 | max_items: 100, 52 | items: { 53 | string: {pattern: "^patterns/[a-z0-9]{26}$"} 54 | } 55 | } 56 | ]; 57 | 58 | // enum options approval state 59 | enum ApprovalState { 60 | // Default 61 | APPROVAL_STATE_UNSPECIFIED = 0; 62 | // Pending 63 | PENDING_APPROVAL = 1; 64 | // Approved 65 | APPROVED = 2; 66 | // rejected 67 | REJECTED = 3; 68 | } 69 | 70 | // explicitly include the zero value 71 | ApprovalState approval_state = 5 [ 72 | (validate.rules).enum = {in: [ 0, 2, 3 ]} 73 | ]; 74 | } 75 | -------------------------------------------------------------------------------- /examples/tests/validate/openapi.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 0.0.1 8 | paths: 9 | /v1/messages/{message_id}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: Update Message Summary 14 | description: This function updates a message. 15 | operationId: Messaging_UpdateMessage 16 | parameters: 17 | - name: message_id 18 | in: path 19 | required: true 20 | schema: 21 | type: string 22 | - name: mynum 23 | in: query 24 | schema: 25 | maximum: !!float 30 26 | minimum: !!float 1 27 | type: integer 28 | format: int64 29 | - name: patterns 30 | in: query 31 | schema: 32 | maxItems: 100 33 | minItems: 1 34 | type: array 35 | items: 36 | pattern: ^patterns/[a-z0-9]{26}$ 37 | type: string 38 | - name: approval_state 39 | in: query 40 | description: explicitly include the zero value 41 | schema: 42 | enum: 43 | - APPROVAL_STATE_UNSPECIFIED 44 | - APPROVED 45 | - REJECTED 46 | type: string 47 | format: enum 48 | requestBody: 49 | content: 50 | application/json: 51 | schema: 52 | type: string 53 | required: true 54 | responses: 55 | "200": 56 | description: OK 57 | content: 58 | application/json: 59 | schema: 60 | $ref: '#/components/schemas/Message' 61 | default: 62 | description: Default error response 63 | content: 64 | application/json: 65 | schema: 66 | $ref: '#/components/schemas/Status' 67 | components: 68 | schemas: 69 | GoogleProtobufAny: 70 | type: object 71 | properties: 72 | '@type': 73 | type: string 74 | description: The type of the serialized message. 75 | additionalProperties: true 76 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 77 | Message: 78 | type: object 79 | properties: 80 | message_id: 81 | type: string 82 | text: 83 | maxLength: 45 84 | minLength: 1 85 | type: string 86 | format: uri 87 | mynum: 88 | maximum: !!float 30 89 | minimum: !!float 1 90 | type: integer 91 | format: int64 92 | patterns: 93 | maxItems: 100 94 | minItems: 1 95 | type: array 96 | items: 97 | pattern: ^patterns/[a-z0-9]{26}$ 98 | type: string 99 | approval_state: 100 | enum: 101 | - APPROVAL_STATE_UNSPECIFIED 102 | - APPROVED 103 | - REJECTED 104 | type: string 105 | description: explicitly include the zero value 106 | format: enum 107 | Status: 108 | type: object 109 | properties: 110 | code: 111 | type: integer 112 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 113 | format: int32 114 | message: 115 | type: string 116 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 117 | details: 118 | type: array 119 | items: 120 | $ref: '#/components/schemas/GoogleProtobufAny' 121 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 122 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 123 | tags: 124 | - name: Messaging 125 | -------------------------------------------------------------------------------- /examples/tests/validate/openapi_json.yaml: -------------------------------------------------------------------------------- 1 | # Generated with protoc-gen-openapi 2 | # https://github.com/kollalabs/protoc-gen-openapi 3 | 4 | openapi: 3.0.3 5 | info: 6 | title: Messaging API 7 | version: 1.2.3 8 | paths: 9 | /v1/messages/{messageId}: 10 | patch: 11 | tags: 12 | - Messaging 13 | summary: Update Message Summary 14 | description: This function updates a message. 15 | operationId: Messaging_UpdateMessage 16 | parameters: 17 | - name: messageId 18 | in: path 19 | required: true 20 | schema: 21 | type: string 22 | - name: mynum 23 | in: query 24 | schema: 25 | maximum: !!float 30 26 | minimum: !!float 1 27 | type: integer 28 | format: int64 29 | - name: patterns 30 | in: query 31 | schema: 32 | maxItems: 100 33 | minItems: 1 34 | type: array 35 | items: 36 | pattern: ^patterns/[a-z0-9]{26}$ 37 | type: string 38 | - name: approvalState 39 | in: query 40 | description: explicitly include the zero value 41 | schema: 42 | enum: 43 | - APPROVAL_STATE_UNSPECIFIED 44 | - APPROVED 45 | - REJECTED 46 | type: string 47 | format: enum 48 | requestBody: 49 | content: 50 | application/json: 51 | schema: 52 | type: string 53 | required: true 54 | responses: 55 | "200": 56 | description: OK 57 | content: 58 | application/json: 59 | schema: 60 | $ref: '#/components/schemas/Message' 61 | default: 62 | description: Default error response 63 | content: 64 | application/json: 65 | schema: 66 | $ref: '#/components/schemas/Status' 67 | components: 68 | schemas: 69 | GoogleProtobufAny: 70 | type: object 71 | properties: 72 | '@type': 73 | type: string 74 | description: The type of the serialized message. 75 | additionalProperties: true 76 | description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. 77 | Message: 78 | type: object 79 | properties: 80 | messageId: 81 | type: string 82 | text: 83 | maxLength: 45 84 | minLength: 1 85 | type: string 86 | format: uri 87 | mynum: 88 | maximum: !!float 30 89 | minimum: !!float 1 90 | type: integer 91 | format: int64 92 | patterns: 93 | maxItems: 100 94 | minItems: 1 95 | type: array 96 | items: 97 | pattern: ^patterns/[a-z0-9]{26}$ 98 | type: string 99 | approvalState: 100 | enum: 101 | - APPROVAL_STATE_UNSPECIFIED 102 | - APPROVED 103 | - REJECTED 104 | type: string 105 | description: explicitly include the zero value 106 | format: enum 107 | Status: 108 | type: object 109 | properties: 110 | code: 111 | type: integer 112 | description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 113 | format: int32 114 | message: 115 | type: string 116 | description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 117 | details: 118 | type: array 119 | items: 120 | $ref: '#/components/schemas/GoogleProtobufAny' 121 | description: A list of messages that carry the error details. There is a common set of message types for APIs to use. 122 | description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' 123 | tags: 124 | - name: Messaging 125 | -------------------------------------------------------------------------------- /gen.sh: -------------------------------------------------------------------------------- 1 | protoc \ 2 | --go_out=./ --go_opt=paths=source_relative \ 3 | openapi/annotations.proto -------------------------------------------------------------------------------- /generator/enum.go: -------------------------------------------------------------------------------- 1 | package generator 2 | 3 | import ( 4 | "strings" 5 | 6 | v3 "github.com/google/gnostic/openapiv3" 7 | "google.golang.org/protobuf/reflect/protoreflect" 8 | ) 9 | 10 | func enumKindSchema(field protoreflect.FieldDescriptor) *v3.SchemaOrReference { 11 | list := enumsToV3Any(field) 12 | 13 | s := &v3.SchemaOrReference{ 14 | Oneof: &v3.SchemaOrReference_Schema{ 15 | Schema: &v3.Schema{ 16 | Format: "enum", 17 | Type: "string", 18 | Enum: list, 19 | }, 20 | }, 21 | } 22 | 23 | return s 24 | } 25 | 26 | func enumsToV3Any(field protoreflect.FieldDescriptor, enumValues ...int32) []*v3.Any { 27 | 28 | stringList := enumToStringSlice(field, enumValues...) 29 | list := []*v3.Any{} 30 | for _, v := range stringList { 31 | n := &v3.Any{ 32 | Yaml: string(v), 33 | } 34 | list = append(list, n) 35 | } 36 | return list 37 | } 38 | 39 | func enumToStringSlice(field protoreflect.FieldDescriptor, enumValues ...int32) []string { 40 | removeUnspecified := len(enumValues) == 0 41 | list := []string{} 42 | values := field.Enum().Values() 43 | for i := 0; i < values.Len(); i++ { 44 | if len(enumValues) == 0 || has(enumValues, int32(values.Get(i).Index())) { 45 | v := values.Get(i) 46 | // skip default unspecified values 47 | if removeUnspecified && strings.HasSuffix(string(v.Name()), "_UNSPECIFIED") { 48 | continue 49 | } 50 | list = append(list, string(v.Name())) 51 | } 52 | } 53 | 54 | return list 55 | } 56 | 57 | // enumValues returns of list of enum ids for a given field 58 | func enumValues(field protoreflect.FieldDescriptor, removeUnspecified bool) []int32 { 59 | values := field.Enum().Values() 60 | var list []int32 61 | for i := 0; i < values.Len(); i++ { 62 | v := values.Get(i) 63 | // skip default unspecified values 64 | if removeUnspecified && strings.HasSuffix(string(v.Name()), "_UNSPECIFIED") { 65 | continue 66 | } 67 | 68 | list = append(list, int32(values.Get(i).Index())) 69 | } 70 | return list 71 | } 72 | 73 | func remove(list []int32, idxs ...int32) []int32 { 74 | var filtered []int32 75 | for _, v := range idxs { 76 | if !has(list, v) { 77 | filtered = append(filtered, int32(v)) 78 | } 79 | } 80 | return filtered 81 | } 82 | 83 | func has(list []int32, idx int32) bool { 84 | for _, v := range list { 85 | if v == idx { 86 | return true 87 | } 88 | } 89 | return false 90 | } 91 | -------------------------------------------------------------------------------- /generator/reflector.go: -------------------------------------------------------------------------------- 1 | // Copyright 2020 Google LLC. All Rights Reserved. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | // 15 | 16 | package generator 17 | 18 | import ( 19 | "log" 20 | "strings" 21 | 22 | "google.golang.org/protobuf/reflect/protoreflect" 23 | 24 | wk "github.com/google/gnostic/cmd/protoc-gen-openapi/generator/wellknown" 25 | v3 "github.com/google/gnostic/openapiv3" 26 | ) 27 | 28 | const ( 29 | protobufValueName = "GoogleProtobufValue" 30 | protobufAnyName = "GoogleProtobufAny" 31 | ) 32 | 33 | type OpenAPIv3Reflector struct { 34 | conf Configuration 35 | 36 | requiredSchemas []string // Names of schemas which are used through references. 37 | } 38 | 39 | // NewOpenAPIv3Reflector creates a new reflector. 40 | func NewOpenAPIv3Reflector(conf Configuration) *OpenAPIv3Reflector { 41 | return &OpenAPIv3Reflector{ 42 | conf: conf, 43 | 44 | requiredSchemas: make([]string, 0), 45 | } 46 | } 47 | 48 | func (r *OpenAPIv3Reflector) getMessageName(message protoreflect.MessageDescriptor) string { 49 | return getMessageName(message) 50 | } 51 | 52 | func getMessageName(message protoreflect.MessageDescriptor) string { 53 | prefix := "" 54 | parent := message.Parent() 55 | 56 | if _, ok := parent.(protoreflect.MessageDescriptor); ok { 57 | prefix = string(parent.Name()) + "_" + prefix 58 | } 59 | 60 | return prefix + string(message.Name()) 61 | } 62 | 63 | func (r *OpenAPIv3Reflector) formatMessageName(message protoreflect.MessageDescriptor) string { 64 | typeName := r.fullMessageTypeName(message) 65 | 66 | name := r.getMessageName(message) 67 | if !*r.conf.FQSchemaNaming { 68 | if typeName == ".google.protobuf.Value" { 69 | name = protobufValueName 70 | } else if typeName == ".google.protobuf.Any" { 71 | name = protobufAnyName 72 | } 73 | } 74 | 75 | if *r.conf.Naming == "json" { 76 | if len(name) > 1 { 77 | name = strings.ToUpper(name[0:1]) + name[1:] 78 | } 79 | 80 | if len(name) == 1 { 81 | name = strings.ToLower(name) 82 | } 83 | } 84 | 85 | if *r.conf.FQSchemaNaming { 86 | package_name := string(message.ParentFile().Package()) 87 | name = package_name + "." + name 88 | } 89 | 90 | return name 91 | } 92 | 93 | func (r *OpenAPIv3Reflector) formatFieldName(field protoreflect.FieldDescriptor) string { 94 | if *r.conf.Naming == "proto" { 95 | return string(field.Name()) 96 | } 97 | 98 | return field.JSONName() 99 | } 100 | 101 | // fullMessageTypeName builds the full type name of a message. 102 | func (r *OpenAPIv3Reflector) fullMessageTypeName(message protoreflect.MessageDescriptor) string { 103 | return fullMessageTypeName(message) 104 | } 105 | 106 | func fullMessageTypeName(message protoreflect.MessageDescriptor) string { 107 | name := getMessageName(message) 108 | return "." + string(message.ParentFile().Package()) + "." + name 109 | } 110 | 111 | func (r *OpenAPIv3Reflector) responseContentForMessage(message protoreflect.MessageDescriptor) (string, *v3.MediaTypes) { 112 | typeName := r.fullMessageTypeName(message) 113 | 114 | if typeName == ".google.protobuf.Empty" { 115 | return "200", &v3.MediaTypes{} 116 | } 117 | 118 | if typeName == ".google.api.HttpBody" { 119 | return "200", wk.NewGoogleApiHttpBodyMediaType() 120 | } 121 | 122 | return "200", wk.NewApplicationJsonMediaType(r.schemaOrReferenceForMessage(message)) 123 | } 124 | 125 | func (r *OpenAPIv3Reflector) schemaReferenceForMessage(message protoreflect.MessageDescriptor) string { 126 | schemaName := r.formatMessageName(message) 127 | if !contains(r.requiredSchemas, schemaName) { 128 | r.requiredSchemas = append(r.requiredSchemas, schemaName) 129 | } 130 | return "#/components/schemas/" + schemaName 131 | } 132 | 133 | // Returns a full schema for simple types, and a schema reference for complex types that reference 134 | // the definition in `#/components/schemas/` 135 | func (r *OpenAPIv3Reflector) schemaOrReferenceForMessage(message protoreflect.MessageDescriptor) *v3.SchemaOrReference { 136 | typeName := r.fullMessageTypeName(message) 137 | switch typeName { 138 | 139 | case ".google.api.HttpBody": 140 | return wk.NewGoogleApiHttpBodySchema() 141 | 142 | case ".google.protobuf.Timestamp": 143 | return wk.NewGoogleProtobufTimestampSchema() 144 | 145 | case ".google.protobuf.Duration": 146 | return NewGoogleProtobufDurationSchema() 147 | 148 | case ".google.type.Date": 149 | return wk.NewGoogleTypeDateSchema() 150 | 151 | case ".google.type.DateTime": 152 | return wk.NewGoogleTypeDateTimeSchema() 153 | 154 | case ".google.protobuf.FieldMask": 155 | return wk.NewGoogleProtobufFieldMaskSchema() 156 | 157 | case ".google.protobuf.Struct": 158 | return wk.NewGoogleProtobufStructSchema() 159 | 160 | case ".google.protobuf.Empty": 161 | // Empty is closer to JSON undefined than null, so ignore this field 162 | return nil //&v3.SchemaOrReference{Oneof: &v3.SchemaOrReference_Schema{Schema: &v3.Schema{Type: "null"}}} 163 | 164 | case ".google.protobuf.BoolValue": 165 | return &v3.SchemaOrReference{ 166 | Oneof: &v3.SchemaOrReference_Schema{ 167 | Schema: &v3.Schema{Type: "boolean", Nullable: true}}} 168 | 169 | case ".google.protobuf.BytesValue": 170 | return &v3.SchemaOrReference{ 171 | Oneof: &v3.SchemaOrReference_Schema{ 172 | Schema: &v3.Schema{Type: "string", Format: "byte", Nullable: true}}} 173 | 174 | case ".google.protobuf.DoubleValue", ".google.protobuf.FloatValue": 175 | return &v3.SchemaOrReference{ 176 | Oneof: &v3.SchemaOrReference_Schema{ 177 | Schema: &v3.Schema{Type: "number", Nullable: true, Format: "float"}}} // TODO: put the correct format here 178 | 179 | case ".google.protobuf.Int64Value", ".google.protobuf.UInt64Value", 180 | ".google.protobuf.Int32Value", ".google.protobuf.UInt32Value": 181 | return &v3.SchemaOrReference{ 182 | Oneof: &v3.SchemaOrReference_Schema{ 183 | Schema: &v3.Schema{Type: "integer", Nullable: true}}} // TODO: put the correct format here 184 | 185 | case ".google.protobuf.StringValue": 186 | return &v3.SchemaOrReference{ 187 | Oneof: &v3.SchemaOrReference_Schema{ 188 | Schema: &v3.Schema{Type: "string", Nullable: true}}} 189 | 190 | default: 191 | ref := r.schemaReferenceForMessage(message) 192 | return &v3.SchemaOrReference{ 193 | Oneof: &v3.SchemaOrReference_Reference{ 194 | Reference: &v3.Reference{XRef: ref}}} 195 | } 196 | 197 | } 198 | 199 | func (r *OpenAPIv3Reflector) schemaOrReferenceForField(field protoreflect.FieldDescriptor) *v3.SchemaOrReference { 200 | var kindSchema *v3.SchemaOrReference 201 | 202 | kind := field.Kind() 203 | 204 | switch kind { 205 | 206 | case protoreflect.MessageKind: 207 | if field.IsMap() { 208 | // This means the field is a map, for example: 209 | // map map_field = 1; 210 | // 211 | // The map ends up getting converted into something like this: 212 | // message MapFieldEntry { 213 | // string key = 1; 214 | // value_type value = 2; 215 | // } 216 | // 217 | // repeated MapFieldEntry map_field = N; 218 | // 219 | // So we need to find the `value` field in the `MapFieldEntry` message and 220 | // then return a MapFieldEntry schema using the schema for the `value` field 221 | return wk.NewGoogleProtobufMapFieldEntrySchema(r.schemaOrReferenceForField(field.MapValue())) 222 | } else { 223 | kindSchema = r.schemaOrReferenceForMessage(field.Message()) 224 | } 225 | 226 | case protoreflect.StringKind: 227 | kindSchema = wk.NewStringSchema() 228 | 229 | case protoreflect.Int32Kind, protoreflect.Sint32Kind, protoreflect.Uint32Kind, 230 | protoreflect.Int64Kind, protoreflect.Sint64Kind, protoreflect.Uint64Kind, 231 | protoreflect.Sfixed32Kind, protoreflect.Fixed32Kind, protoreflect.Sfixed64Kind, 232 | protoreflect.Fixed64Kind: 233 | kindSchema = wk.NewIntegerSchema(kind.String()) 234 | 235 | case protoreflect.EnumKind: 236 | kindSchema = enumKindSchema(field) // Kolla custom behavior for enums 237 | 238 | case protoreflect.BoolKind: 239 | kindSchema = wk.NewBooleanSchema() 240 | 241 | case protoreflect.FloatKind, protoreflect.DoubleKind: 242 | kindSchema = wk.NewNumberSchema(kind.String()) 243 | 244 | case protoreflect.BytesKind: 245 | kindSchema = &v3.SchemaOrReference{ 246 | Oneof: &v3.SchemaOrReference_Schema{ 247 | Schema: &v3.Schema{Type: "string", Format: "byte"}}} 248 | 249 | default: 250 | log.Printf("(TODO) Unsupported field type: %+v", r.fullMessageTypeName(field.Message())) 251 | } 252 | 253 | if field.IsList() { 254 | kindSchema = wk.NewListSchema(kindSchema) 255 | } 256 | 257 | return kindSchema 258 | } 259 | 260 | // google.protobuf.Timestamp is serialized as a string 261 | func NewGoogleProtobufDurationSchema() *v3.SchemaOrReference { 262 | return &v3.SchemaOrReference{ 263 | Oneof: &v3.SchemaOrReference_Schema{ 264 | Schema: &v3.Schema{Type: "string"}}} 265 | } 266 | -------------------------------------------------------------------------------- /generator/utils.go: -------------------------------------------------------------------------------- 1 | // Copyright 2020 Google LLC. All Rights Reserved. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | // 15 | 16 | package generator 17 | 18 | import ( 19 | "strings" 20 | 21 | "google.golang.org/protobuf/compiler/protogen" 22 | ) 23 | 24 | // contains returns true if an array contains a specified string. 25 | func contains(s []string, e string) bool { 26 | for _, a := range s { 27 | if a == e { 28 | return true 29 | } 30 | } 31 | return false 32 | } 33 | 34 | // appendUnique appends a string, to a string slice, if the string is not already in the slice 35 | func appendUnique(s []string, e string) []string { 36 | if !contains(s, e) { 37 | return append(s, e) 38 | } 39 | return s 40 | } 41 | 42 | // singular produces the singular form of a collection name. 43 | func singular(plural string) string { 44 | if strings.HasSuffix(plural, "ves") { 45 | return strings.TrimSuffix(plural, "ves") + "f" 46 | } 47 | if strings.HasSuffix(plural, "ies") { 48 | if plural == "series" || plural == "species" { 49 | return plural 50 | } else { 51 | return strings.TrimSuffix(plural, "ies") + "y" 52 | } 53 | } 54 | if strings.HasSuffix(plural, "s") { 55 | return strings.TrimSuffix(plural, "s") 56 | } 57 | return plural 58 | } 59 | 60 | // filterCommentStringForSummary prepares comment (or method name if there is no comment) for summary value on methods 61 | func (g *OpenAPIv3Generator) filterCommentStringForSummary(c protogen.Comments, goName string) string { 62 | comment := string(c) 63 | split := strings.Split(comment, "|") 64 | if len(split) >= 2 { 65 | comment = split[0] 66 | } else { 67 | comment = goName 68 | } 69 | comment = g.linterRulePattern.ReplaceAllString(comment, "") 70 | return strings.TrimSpace(comment) 71 | } 72 | -------------------------------------------------------------------------------- /generator/utils_test.go: -------------------------------------------------------------------------------- 1 | package generator 2 | 3 | import ( 4 | "strings" 5 | "testing" 6 | 7 | "google.golang.org/protobuf/compiler/protogen" 8 | ) 9 | 10 | func TestSummary(t *testing.T) { 11 | g := NewOpenAPIv3Generator(nil, Configuration{}) 12 | var comments protogen.Comments = `This function updates a message. 13 | (-- api-linter: core::0xxx::xxx=disabled 14 | aip.dev/not-precedent: We need to do this because reasons. --) 15 | ` 16 | filtered := g.linterRulePattern.ReplaceAllString(string(comments), "") 17 | if strings.Contains(filtered, "0xxx") { 18 | t.Fatalf("linter rule pattern did not remove linter message\n %s\n", filtered) 19 | } 20 | 21 | } 22 | -------------------------------------------------------------------------------- /generator/validate.go: -------------------------------------------------------------------------------- 1 | package generator 2 | 3 | import ( 4 | "log" 5 | 6 | "github.com/envoyproxy/protoc-gen-validate/validate" 7 | v3 "github.com/google/gnostic/openapiv3" 8 | "google.golang.org/protobuf/proto" 9 | "google.golang.org/protobuf/reflect/protoreflect" 10 | ) 11 | 12 | func (g *OpenAPIv3Generator) addValidationRules(fieldSchema *v3.SchemaOrReference, field protoreflect.FieldDescriptor) { 13 | validationRules := proto.GetExtension(field.Options(), validate.E_Rules) 14 | if validationRules == nil { 15 | return 16 | } 17 | fieldRules, ok := validationRules.(*validate.FieldRules) 18 | if !ok { 19 | return 20 | } 21 | schema, ok := fieldSchema.Oneof.(*v3.SchemaOrReference_Schema) 22 | if !ok { 23 | return 24 | } 25 | 26 | //TODO: implement map validation 27 | if field.IsMap() { 28 | return 29 | } 30 | 31 | if field.IsList() { 32 | repeatedRules := fieldRules.GetRepeated() 33 | if repeatedRules == nil { 34 | // no rules 35 | return 36 | } 37 | // MinItems specifies that this field must have the specified number of 38 | // items at a minimum 39 | // MaxItems specifies that this field must have the specified number of 40 | // items at a maximum 41 | // Unique specifies that all elements in this field must be unique. This 42 | // contraint is only applicable to scalar and enum types (messages are not 43 | // supported). 44 | // Items specifies the contraints to be applied to each item in the field. 45 | // Repeated message fields will still execute validation against each item 46 | // unless skip is specified here. 47 | // IgnoreEmpty specifies that the validation rules of this field should be 48 | // evaluated only if the field is not empty 49 | if repeatedRules.MinItems != nil { 50 | schema.Schema.MinItems = int64(*repeatedRules.MinItems) 51 | } 52 | if repeatedRules.MaxItems != nil { 53 | schema.Schema.MaxItems = int64(*repeatedRules.MaxItems) 54 | } 55 | 56 | // pull out the array items field rules 57 | fieldRules := repeatedRules.Items 58 | if fieldRules == nil { 59 | // no item specific rules 60 | return 61 | } 62 | schema := schema.Schema.Items.SchemaOrReference[0] 63 | fieldRule(fieldRules, field, schema.Oneof.(*v3.SchemaOrReference_Schema)) 64 | 65 | log.Printf("(TODO) Unsupported field type: list.") 66 | return 67 | } 68 | 69 | fieldRule(fieldRules, field, schema) 70 | 71 | } 72 | 73 | func fieldRule(fieldRules *validate.FieldRules, field protoreflect.FieldDescriptor, schema *v3.SchemaOrReference_Schema) { 74 | 75 | kind := field.Kind() 76 | switch kind { 77 | 78 | case protoreflect.MessageKind: 79 | return // TO DO: Implement message validators from protoc-gen-validate 80 | 81 | case protoreflect.StringKind: 82 | stringRules := fieldRules.GetString_() 83 | if stringRules == nil { 84 | break 85 | } 86 | // Set Format 87 | // format is an open value, so you can use any formats, even not those defined by the OpenAPI Specification 88 | if stringRules.GetEmail() { 89 | schema.Schema.Format = "email" 90 | } else if stringRules.GetHostname() { 91 | schema.Schema.Format = "hostname" 92 | } else if stringRules.GetIp() { 93 | schema.Schema.Format = "ip" 94 | } else if stringRules.GetIpv4() { 95 | schema.Schema.Format = "ipv4" 96 | } else if stringRules.GetIpv6() { 97 | schema.Schema.Format = "ipv6" 98 | } else if stringRules.GetUri() { 99 | schema.Schema.Format = "uri" 100 | } else if stringRules.GetUriRef() { 101 | schema.Schema.Format = "uri_ref" 102 | } else if stringRules.GetUuid() { 103 | schema.Schema.Format = "uuid" 104 | } 105 | // Set min/max 106 | if stringRules.GetMinLen() > 0 { 107 | schema.Schema.MinLength = int64(stringRules.GetMinLen()) 108 | } 109 | if stringRules.GetMaxLen() > 0 { 110 | schema.Schema.MaxLength = int64(stringRules.GetMaxLen()) 111 | } 112 | // Set Pattern 113 | if stringRules.GetPattern() != "" { 114 | schema.Schema.Pattern = stringRules.GetPattern() 115 | } 116 | 117 | case protoreflect.Int32Kind: 118 | int32Rules := fieldRules.GetInt32() 119 | if int32Rules == nil { 120 | break 121 | } 122 | if int32Rules.GetGte() > 0 { 123 | schema.Schema.Minimum = float64(int32Rules.GetGte()) 124 | } 125 | if int32Rules.GetLte() > 0 { 126 | schema.Schema.Maximum = float64(int32Rules.GetLte()) 127 | } 128 | 129 | case protoreflect.Int64Kind: 130 | int64Rules := fieldRules.GetInt64() 131 | if int64Rules == nil { 132 | break 133 | } 134 | if int64Rules.GetGte() > 0 { 135 | schema.Schema.Minimum = float64(int64Rules.GetGte()) 136 | } 137 | if int64Rules.GetLte() > 0 { 138 | schema.Schema.Maximum = float64(int64Rules.GetLte()) 139 | } 140 | case protoreflect.EnumKind: 141 | enumRules := fieldRules.GetEnum() 142 | if enumRules == nil { 143 | break 144 | } 145 | 146 | var validEnums []int32 147 | if enumRules.Const != nil { 148 | validEnums = enumValues(field, true) 149 | } else if enumRules.In != nil { 150 | validEnums = enumRules.In 151 | } else if enumRules.NotIn != nil { 152 | validEnums = remove(enumValues(field, false), enumRules.NotIn...) 153 | } 154 | // we don't check enumRules.DefinedOnly because we already list the set of valid enums 155 | list := enumsToV3Any(field, validEnums...) 156 | schema.Schema.Enum = list 157 | 158 | //TODO: implement protoc-gen-validate rules for the following types 159 | case protoreflect.Sint32Kind, protoreflect.Uint32Kind, 160 | protoreflect.Sint64Kind, protoreflect.Uint64Kind, 161 | protoreflect.Sfixed32Kind, protoreflect.Fixed32Kind, protoreflect.Sfixed64Kind, 162 | protoreflect.Fixed64Kind: 163 | 164 | case protoreflect.BoolKind: 165 | 166 | case protoreflect.FloatKind, protoreflect.DoubleKind: 167 | 168 | case protoreflect.BytesKind: 169 | 170 | default: 171 | log.Printf("(TODO) Unsupported field type: %+v", fullMessageTypeName(field.Message())) 172 | } 173 | } 174 | -------------------------------------------------------------------------------- /go.mod: -------------------------------------------------------------------------------- 1 | module github.com/kollalabs/protoc-gen-openapi 2 | 3 | go 1.24 4 | 5 | require ( 6 | github.com/envoyproxy/protoc-gen-validate v1.2.1 7 | github.com/golang/protobuf v1.5.4 8 | github.com/google/gnostic v0.7.0 9 | google.golang.org/genproto/googleapis/api v0.0.0-20250425173222-7b384671a197 10 | google.golang.org/genproto/googleapis/rpc v0.0.0-20250425173222-7b384671a197 11 | google.golang.org/protobuf v1.36.6 12 | ) 13 | 14 | require ( 15 | github.com/google/gnostic-models v0.6.9-0.20230804172637-c7be7c783f49 // indirect 16 | gopkg.in/yaml.v3 v3.0.1 // indirect 17 | ) 18 | -------------------------------------------------------------------------------- /main.go: -------------------------------------------------------------------------------- 1 | // Copyright 2020 Google LLC. All Rights Reserved. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | // 15 | 16 | package main 17 | 18 | import ( 19 | "flag" 20 | 21 | "github.com/kollalabs/protoc-gen-openapi/generator" 22 | "google.golang.org/protobuf/compiler/protogen" 23 | "google.golang.org/protobuf/types/pluginpb" 24 | ) 25 | 26 | var flags flag.FlagSet 27 | 28 | func main() { 29 | conf := generator.Configuration{ 30 | Version: flags.String("version", "0.0.1", "version number text, e.g. 1.2.3"), 31 | Title: flags.String("title", "", "name of the API"), 32 | Description: flags.String("description", "", "description of the API"), 33 | Naming: flags.String("naming", "json", `naming convention. Use "proto" for passing names directly from the proto files`), 34 | FQSchemaNaming: flags.Bool("fq_schema_naming", false, `schema naming convention. If "true", generates fully-qualified schema names by prefixing them with the proto message package name`), 35 | EnumType: flags.String("enum_type", "integer", `type for enum serialization. Use "string" for string-based serialization`), 36 | CircularDepth: flags.Int("depth", 2, "depth of recursion for circular messages"), 37 | DefaultResponse: flags.Bool("default_response", true, `add default response. If "true", automatically adds a default response to operations which use the google.rpc.Status message. Useful if you use envoy or grpc-gateway to transcode as they use this type for their default error responses.`), 38 | Validate: flags.Bool("validate", false, "parse protoc-gen-validate options that are supported into openapi field options"), 39 | BuildTag: flags.String("build_tag", "", "build tag to add to the generated files"), 40 | } 41 | 42 | opts := protogen.Options{ 43 | ParamFunc: flags.Set, 44 | } 45 | 46 | opts.Run(func(plugin *protogen.Plugin) error { 47 | // Enable "optional" keyword in front of type (e.g. optional string labe = 1;) 48 | plugin.SupportedFeatures = uint64(pluginpb.CodeGeneratorResponse_FEATURE_PROTO3_OPTIONAL) 49 | return generator.NewOpenAPIv3Generator(plugin, conf).Run() 50 | }) 51 | } 52 | -------------------------------------------------------------------------------- /main_test.go: -------------------------------------------------------------------------------- 1 | package main 2 | 3 | import ( 4 | "log" 5 | "os" 6 | "os/exec" 7 | "testing" 8 | ) 9 | 10 | func TestMain(m *testing.M) { 11 | 12 | // build and install protoc plugin before running tests 13 | out, err := exec.Command("go", "install").CombinedOutput() 14 | if err != nil { 15 | log.Println(string(out)) 16 | log.Println(err) 17 | os.Exit(1) 18 | } 19 | 20 | os.Exit(m.Run()) 21 | } 22 | -------------------------------------------------------------------------------- /openapi/annotations.proto: -------------------------------------------------------------------------------- 1 | syntax = "proto2"; 2 | 3 | package openapi; 4 | 5 | import "google/protobuf/descriptor.proto"; 6 | 7 | option go_package = "github.com/kollalabs/protoc-gen-openapi/openapi;openapi"; 8 | 9 | // Add openAPI parameters to a method 10 | extend google.protobuf.MethodOptions { 11 | optional Parameters method_params = 66700; 12 | } 13 | 14 | // Add parameters that are added to every method in a service 15 | extend google.protobuf.ServiceOptions { 16 | optional Parameters service_params = 66701; 17 | } 18 | 19 | // Parameters at the file level are added to every method in every service in the file 20 | extend google.protobuf.FileOptions { 21 | optional Parameters file_params = 66702; 22 | } 23 | 24 | 25 | message Parameters { 26 | repeated Header headers = 1; 27 | repeated string build_tags = 2; 28 | } 29 | 30 | message Header { 31 | optional string name = 1; 32 | optional string pattern = 2; 33 | optional string description = 3; 34 | optional bool required = 4; 35 | optional string example = 5; 36 | } 37 | -------------------------------------------------------------------------------- /plugin_test.go: -------------------------------------------------------------------------------- 1 | // Copyright 2020 Google LLC. All Rights Reserved. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the "License"); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an "AS IS" BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | package main 16 | 17 | import ( 18 | "fmt" 19 | "os" 20 | "os/exec" 21 | "path" 22 | "strings" 23 | "testing" 24 | ) 25 | 26 | var openapiTests = []struct { 27 | name string 28 | path string 29 | protofile string 30 | buildTag []string 31 | }{ 32 | {name: "Google Library example", path: "examples/google/example/library/v1/", protofile: "library.proto"}, 33 | {name: "Body mapping", path: "examples/tests/bodymapping/", protofile: "message.proto"}, 34 | {name: "Map fields", path: "examples/tests/mapfields/", protofile: "message.proto"}, 35 | {name: "Path params", path: "examples/tests/pathparams/", protofile: "message.proto"}, 36 | {name: "Protobuf types", path: "examples/tests/protobuftypes/", protofile: "message.proto"}, 37 | {name: "JSON options", path: "examples/tests/jsonoptions/", protofile: "message.proto"}, 38 | {name: "Ignore services without annotations", path: "examples/tests/noannotations/", protofile: "message.proto"}, 39 | {name: "Handle enums", path: "examples/tests/enums/", protofile: "message.proto"}, 40 | {name: "Better summary", path: "examples/tests/summary/", protofile: "message.proto"}, 41 | {name: "Message name pattern", path: "examples/tests/messagenamepattern/", protofile: "message.proto"}, 42 | {name: "Validate", path: "examples/tests/validate/", protofile: "message.proto"}, 43 | {name: "Field behaviors", path: "examples/tests/fieldbehaviors/", protofile: "message.proto"}, 44 | {name: "Custom Params", path: "examples/tests/customparams/", protofile: "message.proto"}, 45 | {name: "Custom Params with build tag set", path: "examples/tests/customparamsbuildtag/", protofile: "message.proto", buildTag: []string{"postman"}}, 46 | {name: "Custom Params with build tag set for excluding method", path: "examples/tests/customparamsexclude/", protofile: "message.proto", buildTag: []string{"public_docs"}}, 47 | {name: "Custom Params with build tag postman", path: "examples/tests/customparamspostmanonly/", protofile: "message.proto", buildTag: []string{"postman"}}, 48 | {name: "Custom Params with build tag postman and public_docs", path: "examples/tests/customparamspostmanandpublic/", protofile: "message.proto", buildTag: []string{"postman", "public_docs"}}, 49 | } 50 | 51 | func TestOpenAPIProtobufNaming(t *testing.T) { 52 | for _, tt := range openapiTests { 53 | t.Run(tt.name, func(t *testing.T) { 54 | // Run protoc and the protoc-gen-openapi plugin to generate an OpenAPI spec. 55 | openAPICommand := "--openapi_out=version=0.0.1,naming=proto,validate=true" 56 | //loop over build tags and add them to the command 57 | if len(tt.buildTag) > 0 { 58 | for _, tag := range tt.buildTag { 59 | openAPICommand += ",build_tag=" + tag 60 | } 61 | } 62 | openAPICommand += ":." 63 | cmd := []string{ 64 | "-I", 65 | "./", 66 | "-I", 67 | "examples", 68 | path.Join(tt.path, tt.protofile), 69 | openAPICommand, 70 | } 71 | fmt.Printf("Running protoc %s\n", strings.Join(cmd, " ")) 72 | out, err := exec.Command("protoc", cmd...).CombinedOutput() 73 | if err != nil { 74 | fmt.Println(string(out)) 75 | fmt.Printf("Command: protoc %s\n", strings.Join(cmd, " ")) 76 | t.Fatalf("protoc failed: %+v", err) 77 | } 78 | // Verify that the generated spec matches our expected version. 79 | diffArgs := []string{"-u", "--color", path.Join(tt.path, "openapi.yaml"), "openapi.yaml"} 80 | output, err := exec.Command("diff", diffArgs...).CombinedOutput() 81 | if err != nil { 82 | fmt.Printf("Protoc output:\n%s\n", out) 83 | fmt.Printf("Command: protoc %s\n", strings.Join(cmd, " ")) 84 | fmt.Printf("Command: diff %s\n", strings.Join(diffArgs, " ")) 85 | fmt.Println(string(output)) 86 | t.Fatalf("Diff failed: %+v", err) 87 | } 88 | // if the test succeeded, clean up 89 | os.Remove("openapi.yaml") 90 | }) 91 | } 92 | } 93 | 94 | func TestOpenAPIJSONNaming(t *testing.T) { 95 | for _, tt := range openapiTests { 96 | t.Run(tt.name, func(t *testing.T) { 97 | // Run protoc and the protoc-gen-openapi plugin to generate an OpenAPI spec with JSON naming. 98 | out, err := exec.Command("protoc", 99 | "-I", "./", 100 | "-I", "examples", 101 | path.Join(tt.path, tt.protofile), 102 | "--openapi_out=version=1.2.3,validate=true:.").CombinedOutput() 103 | if err != nil { 104 | fmt.Println(string(out)) 105 | t.Fatalf("protoc failed: %+v", err) 106 | } 107 | 108 | // Verify that the generated spec matches our expected version. 109 | diffArgs := []string{"-u", "--color", path.Join(tt.path, "openapi_json.yaml"), "openapi.yaml"} 110 | output, err := exec.Command("diff", diffArgs...).CombinedOutput() 111 | if err != nil { 112 | fmt.Printf("Protoc output:\n%s\n", out) 113 | fmt.Println("Command: diff", strings.Join(diffArgs, " ")) 114 | fmt.Println(string(output)) 115 | t.Fatalf("Diff failed: %+v", err) 116 | } 117 | // if the test succeeded, clean up 118 | os.Remove("openapi.yaml") 119 | }) 120 | } 121 | } 122 | -------------------------------------------------------------------------------- /run_tests: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | set -eux 4 | 5 | go build -v 6 | 7 | go clean -testcache && go test 8 | --------------------------------------------------------------------------------