Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for OpenAPI YAML annotations #1665

Merged
merged 17 commits into from
Sep 17, 2020
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Add generated files and Bazel rules
jasonewang committed Sep 15, 2020
commit ad06ba4d7d22c396dfaaf91cb4679f1f57699dce
2 changes: 2 additions & 0 deletions examples/internal/clients/unannotatedecho/BUILD.bazel
Original file line number Diff line number Diff line change
@@ -5,9 +5,11 @@ package(default_visibility = ["//visibility:public"])
go_library(
name = "go_default_library",
srcs = [
"api_echo_rpc.go",
"api_unannotated_echo_service.go",
"client.go",
"configuration.go",
"model_examplepb_numeric_enum.go",
"model_examplepb_unannotated_embedded.go",
"model_examplepb_unannotated_simple_message.go",
"model_protobuf_any.go",
169 changes: 142 additions & 27 deletions examples/internal/clients/unannotatedecho/api/swagger.yaml
Original file line number Diff line number Diff line change
@@ -5,19 +5,40 @@ info:
\ annotations. See\nunannotated_echo_service.yaml for the equivalent of the annotations\
\ in\ngRPC API configuration format.\n\nEcho Service API consists of a single\
\ service which returns\na message."
version: "version not set"
title: "examples/internal/proto/examplepb/unannotated_echo_service.proto"
version: "1.0"
title: "Unannotated Echo"
contact:
name: "gRPC-Gateway project"
url: "https://github.com/grpc-ecosystem/grpc-gateway"
email: "none@example.com"
license:
name: "BSD 3-Clause License"
url: "https://github.com/grpc-ecosystem/grpc-gateway/blob/master/LICENSE.txt"
x-something-something: "yadda"
schemes:
- "http"
- "https"
- "wss"
consumes:
- "application/json"
- "application/x-foo-mime"
produces:
- "application/json"
- "application/x-foo-mime"
security:
- ApiKeyAuth: []
BasicAuth: []
- ApiKeyAuth: []
OAuth2:
- "read"
- "write"
paths:
/v1/example/echo/{id}:
post:
tags:
- "UnannotatedEchoService"
summary: "Echo method receives a simple message and returns it."
description: "The message posted as the id parameter will also be\nreturned."
- "echo rpc"
summary: "Summary: Echo rpc"
description: "Description Echo"
operationId: "UnannotatedEchoService_Echo"
parameters:
- name: "id"
@@ -29,18 +50,41 @@ paths:
responses:
200:
description: "A successful response."
examples:
application/json:
value: "the input value"
schema:
$ref: "#/definitions/examplepbUnannotatedSimpleMessage"
403:
description: "Returned when the user does not have permission to access\
\ the resource."
schema: {}
404:
description: "Returned when the resource does not exist."
schema:
type: "integer"
format: "integer"
418:
description: "I'm a teapot."
schema:
$ref: "#/definitions/examplepbNumericEnum"
503:
description: "Returned when the resource is temporarily unavailable."
schema: {}
x-number: 100
default:
description: "An unexpected error response."
schema:
$ref: "#/definitions/rpcStatus"
externalDocs:
description: "Find out more Echo"
url: "https://github.com/grpc-ecosystem/grpc-gateway"
/v1/example/echo/{id}/{num}:
get:
tags:
- "UnannotatedEchoService"
summary: "Echo method receives a simple message and returns it."
description: "The message posted as the id parameter will also be\nreturned."
- "echo rpc"
summary: "Summary: Echo rpc"
description: "Description Echo"
operationId: "UnannotatedEchoService_Echo2"
parameters:
- name: "id"
@@ -51,8 +95,10 @@ paths:
x-exportParamName: "Id"
- name: "num"
in: "path"
description: "Int value field"
required: true
type: "string"
default: "42"
format: "int64"
x-exportParamName: "Num"
- name: "duration"
@@ -110,12 +156,35 @@ paths:
responses:
200:
description: "A successful response."
examples:
application/json:
value: "the input value"
schema:
$ref: "#/definitions/examplepbUnannotatedSimpleMessage"
403:
description: "Returned when the user does not have permission to access\
\ the resource."
schema: {}
404:
description: "Returned when the resource does not exist."
schema:
type: "integer"
format: "integer"
418:
description: "I'm a teapot."
schema:
$ref: "#/definitions/examplepbNumericEnum"
503:
description: "Returned when the resource is temporarily unavailable."
schema: {}
x-number: 100
default:
description: "An unexpected error response."
schema:
$ref: "#/definitions/rpcStatus"
externalDocs:
description: "Find out more Echo"
url: "https://github.com/grpc-ecosystem/grpc-gateway"
/v1/example/echo_body:
post:
tags:
@@ -134,6 +203,19 @@ paths:
description: "A successful response."
schema:
$ref: "#/definitions/examplepbUnannotatedSimpleMessage"
403:
description: "Returned when the user does not have permission to access\
\ the resource."
schema: {}
404:
description: "Returned when the resource does not exist."
schema:
type: "string"
format: "string"
418:
description: "I'm a teapot."
schema:
$ref: "#/definitions/examplepbNumericEnum"
default:
description: "An unexpected error response."
schema:
@@ -154,11 +236,12 @@ paths:
x-optionalDataType: "String"
- name: "num"
in: "query"
required: false
description: "Int value field"
required: true
type: "string"
default: "42"
format: "int64"
x-exportParamName: "Num"
x-optionalDataType: "String"
- name: "duration"
in: "query"
required: false
@@ -216,11 +299,43 @@ paths:
description: "A successful response."
schema:
$ref: "#/definitions/examplepbUnannotatedSimpleMessage"
403:
description: "Returned when the user does not have permission to access\
\ the resource."
schema: {}
404:
description: "Returned when the resource does not exist."
schema:
type: "string"
format: "string"
418:
description: "I'm a teapot."
schema:
$ref: "#/definitions/examplepbNumericEnum"
default:
description: "An unexpected error response."
schema:
$ref: "#/definitions/rpcStatus"
securityDefinitions:
ApiKeyAuth:
type: "apiKey"
name: "X-API-Key"
in: "header"
x-amazon-apigateway-authorizer:
authorizerResultTtlInSeconds: 60
type: "token"
x-amazon-apigateway-authtype: "oauth2"
BasicAuth:
type: "basic"
definitions:
examplepbNumericEnum:
type: "string"
description: "NumericEnum is one or zero.\n\n - ZERO: ZERO means 0\n - ONE: ONE\
\ means 1"
enum:
- "ZERO"
- "ONE"
default: "ZERO"
examplepbUnannotatedEmbedded:
type: "object"
properties:
@@ -230,18 +345,19 @@ definitions:
note:
type: "string"
description: "Embedded represents a message embedded in SimpleMessage."
example:
note: "note"
progress: "progress"
examplepbUnannotatedSimpleMessage:
type: "object"
required:
- "id"
properties:
id:
type: "string"
description: "Id represents the message identifier."
num:
type: "string"
format: "int64"
description: "Int value field"
default: "42"
duration:
type: "string"
lineNum:
@@ -256,21 +372,13 @@ definitions:
format: "int64"
"no":
$ref: "#/definitions/examplepbUnannotatedEmbedded"
description: "UnannotatedSimpleMessage represents a simple message sent to the\
\ unannotated Echo service."
externalDocs:
description: "Find out more about UnannotatedSimpleMessage"
url: "https://github.com/grpc-ecosystem/grpc-gateway"
title: "A bit of everything"
description: "A simple message with many types"
example:
duration: "duration"
"no":
note: "note"
progress: "progress"
num: "num"
lineNum: "lineNum"
en: "en"
id: "id"
lang: "lang"
status:
note: "note"
progress: "progress"
id: "myid"
protobufAny:
type: "object"
properties:
@@ -341,3 +449,10 @@ definitions:
type: "array"
items:
$ref: "#/definitions/protobufAny"
externalDocs:
description: "More about gRPC-Gateway"
url: "https://github.com/grpc-ecosystem/grpc-gateway"
x-grpc-gateway-baz-list:
- "one"
- true
x-grpc-gateway-foo: "bar"
Loading