feat(cmd/kratos): generating API documentation using Gnostic (#1716)
parent
ccb649a201
commit
3642f5d0ba
@ -0,0 +1,126 @@ |
||||
# Generated with protoc-gen-openapi |
||||
# https://github.com/google/gnostic/tree/master/apps/protoc-gen-openapi |
||||
|
||||
openapi: 3.0.3 |
||||
info: |
||||
title: BlogService |
||||
version: 0.0.1 |
||||
paths: |
||||
/v1/article/: |
||||
get: |
||||
operationId: BlogService_ListArticle |
||||
responses: |
||||
"200": |
||||
description: OK |
||||
content: |
||||
application/json: |
||||
schema: |
||||
$ref: '#/components/schemas/ListArticleReply' |
||||
post: |
||||
operationId: BlogService_CreateArticle |
||||
requestBody: |
||||
content: |
||||
application/json: |
||||
schema: |
||||
$ref: '#/components/schemas/CreateArticleRequest' |
||||
required: true |
||||
responses: |
||||
"200": |
||||
description: OK |
||||
content: |
||||
application/json: |
||||
schema: |
||||
$ref: '#/components/schemas/CreateArticleReply' |
||||
/v1/article/{id}: |
||||
get: |
||||
operationId: BlogService_GetArticle |
||||
parameters: |
||||
- name: id |
||||
in: query |
||||
schema: |
||||
type: string |
||||
responses: |
||||
"200": |
||||
description: OK |
||||
content: |
||||
application/json: |
||||
schema: |
||||
$ref: '#/components/schemas/GetArticleReply' |
||||
put: |
||||
operationId: BlogService_UpdateArticle |
||||
requestBody: |
||||
content: |
||||
application/json: |
||||
schema: |
||||
$ref: '#/components/schemas/UpdateArticleRequest' |
||||
required: true |
||||
responses: |
||||
"200": |
||||
description: OK |
||||
content: |
||||
application/json: |
||||
schema: |
||||
$ref: '#/components/schemas/UpdateArticleReply' |
||||
delete: |
||||
operationId: BlogService_DeleteArticle |
||||
parameters: |
||||
- name: id |
||||
in: query |
||||
schema: |
||||
type: string |
||||
responses: |
||||
"200": |
||||
description: OK |
||||
content: |
||||
application/json: |
||||
schema: |
||||
$ref: '#/components/schemas/DeleteArticleReply' |
||||
components: |
||||
schemas: |
||||
Article: |
||||
properties: |
||||
id: |
||||
type: integer |
||||
format: int64 |
||||
title: |
||||
type: string |
||||
content: |
||||
type: string |
||||
like: |
||||
type: integer |
||||
format: int64 |
||||
CreateArticleReply: |
||||
properties: |
||||
Article: |
||||
$ref: '#/components/schemas/Article' |
||||
CreateArticleRequest: |
||||
properties: |
||||
title: |
||||
type: string |
||||
content: |
||||
type: string |
||||
DeleteArticleReply: |
||||
properties: {} |
||||
GetArticleReply: |
||||
properties: |
||||
Article: |
||||
$ref: '#/components/schemas/Article' |
||||
ListArticleReply: |
||||
properties: |
||||
results: |
||||
type: array |
||||
items: |
||||
$ref: '#/components/schemas/Article' |
||||
UpdateArticleReply: |
||||
properties: |
||||
Article: |
||||
$ref: '#/components/schemas/Article' |
||||
UpdateArticleRequest: |
||||
properties: |
||||
id: |
||||
type: integer |
||||
format: int64 |
||||
title: |
||||
type: string |
||||
content: |
||||
type: string |
@ -0,0 +1,101 @@ |
||||
// Copyright 2019 Google LLC. |
||||
// |
||||
// Licensed under the Apache License, Version 2.0 (the "License"); |
||||
// you may not use this file except in compliance with the License. |
||||
// You may obtain a copy of the License at |
||||
// |
||||
// https://www.apache.org/licenses/LICENSE-2.0 |
||||
// |
||||
// Unless required by applicable law or agreed to in writing, software |
||||
// distributed under the License is distributed on an "AS IS" BASIS, |
||||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
||||
// See the License for the specific language governing permissions and |
||||
// limitations under the License. |
||||
|
||||
syntax = "proto3"; |
||||
|
||||
package google.api; |
||||
|
||||
import "google/protobuf/descriptor.proto"; |
||||
|
||||
option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations"; |
||||
option java_multiple_files = true; |
||||
option java_outer_classname = "ClientProto"; |
||||
option java_package = "com.google.api"; |
||||
option objc_class_prefix = "GAPI"; |
||||
|
||||
|
||||
extend google.protobuf.ServiceOptions { |
||||
// The hostname for this service. |
||||
// This should be specified with no prefix or protocol. |
||||
// |
||||
// Example: |
||||
// |
||||
// service Foo { |
||||
// option (google.api.default_host) = "foo.googleapi.com"; |
||||
// ... |
||||
// } |
||||
string default_host = 1049; |
||||
|
||||
// OAuth scopes needed for the client. |
||||
// |
||||
// Example: |
||||
// |
||||
// service Foo { |
||||
// option (google.api.oauth_scopes) = \ |
||||
// "https://www.googleapis.com/auth/cloud-platform"; |
||||
// ... |
||||
// } |
||||
// |
||||
// If there is more than one scope, use a comma-separated string: |
||||
// |
||||
// Example: |
||||
// |
||||
// service Foo { |
||||
// option (google.api.oauth_scopes) = \ |
||||
// "https://www.googleapis.com/auth/cloud-platform," |
||||
// "https://www.googleapis.com/auth/monitoring"; |
||||
// ... |
||||
// } |
||||
string oauth_scopes = 1050; |
||||
} |
||||
|
||||
|
||||
extend google.protobuf.MethodOptions { |
||||
// A definition of a client library method signature. |
||||
// |
||||
// In client libraries, each proto RPC corresponds to one or more methods |
||||
// which the end user is able to call, and calls the underlying RPC. |
||||
// Normally, this method receives a single argument (a struct or instance |
||||
// corresponding to the RPC request object). Defining this field will |
||||
// add one or more overloads providing flattened or simpler method signatures |
||||
// in some languages. |
||||
// |
||||
// The fields on the method signature are provided as a comma-separated |
||||
// string. |
||||
// |
||||
// For example, the proto RPC and annotation: |
||||
// |
||||
// rpc CreateSubscription(CreateSubscriptionRequest) |
||||
// returns (Subscription) { |
||||
// option (google.api.method_signature) = "name,topic"; |
||||
// } |
||||
// |
||||
// Would add the following Java overload (in addition to the method accepting |
||||
// the request object): |
||||
// |
||||
// public final Subscription createSubscription(String name, String topic) |
||||
// |
||||
// The following backwards-compatibility guidelines apply: |
||||
// |
||||
// * Adding this annotation to an unannotated method is backwards |
||||
// compatible. |
||||
// * Adding this annotation to a method which already has existing |
||||
// method signature annotations is backwards compatible if and only if |
||||
// the new method signature annotation is last in the sequence. |
||||
// * Modifying or removing an existing method signature annotation is |
||||
// a breaking change. |
||||
// * Re-ordering existing method signature annotations is a breaking |
||||
// change. |
||||
repeated string method_signature = 1051; |
||||
} |
@ -0,0 +1,80 @@ |
||||
// Copyright 2019 Google LLC. |
||||
// |
||||
// Licensed under the Apache License, Version 2.0 (the "License"); |
||||
// you may not use this file except in compliance with the License. |
||||
// You may obtain a copy of the License at |
||||
// |
||||
// https://www.apache.org/licenses/LICENSE-2.0 |
||||
// |
||||
// Unless required by applicable law or agreed to in writing, software |
||||
// distributed under the License is distributed on an "AS IS" BASIS, |
||||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
||||
// See the License for the specific language governing permissions and |
||||
// limitations under the License. |
||||
|
||||
syntax = "proto3"; |
||||
|
||||
package google.api; |
||||
|
||||
import "google/protobuf/descriptor.proto"; |
||||
|
||||
option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations"; |
||||
option java_multiple_files = true; |
||||
option java_outer_classname = "FieldBehaviorProto"; |
||||
option java_package = "com.google.api"; |
||||
option objc_class_prefix = "GAPI"; |
||||
|
||||
|
||||
// An indicator of the behavior of a given field (for example, that a field |
||||
// is required in requests, or given as output but ignored as input). |
||||
// This **does not** change the behavior in protocol buffers itself; it only |
||||
// denotes the behavior and may affect how API tooling handles the field. |
||||
// |
||||
// Note: This enum **may** receive new values in the future. |
||||
enum FieldBehavior { |
||||
// Conventional default for enums. Do not use this. |
||||
FIELD_BEHAVIOR_UNSPECIFIED = 0; |
||||
|
||||
// Specifically denotes a field as optional. |
||||
// While all fields in protocol buffers are optional, this may be specified |
||||
// for emphasis if appropriate. |
||||
OPTIONAL = 1; |
||||
|
||||
// Denotes a field as required. |
||||
// This indicates that the field **must** be provided as part of the request, |
||||
// and failure to do so will cause an error (usually `INVALID_ARGUMENT`). |
||||
REQUIRED = 2; |
||||
|
||||
// Denotes a field as output only. |
||||
// This indicates that the field is provided in responses, but including the |
||||
// field in a request does nothing (the server *must* ignore it and |
||||
// *must not* throw an error as a result of the field's presence). |
||||
OUTPUT_ONLY = 3; |
||||
|
||||
// Denotes a field as input only. |
||||
// This indicates that the field is provided in requests, and the |
||||
// corresponding field is not included in output. |
||||
INPUT_ONLY = 4; |
||||
|
||||
// Denotes a field as immutable. |
||||
// This indicates that the field may be set once in a request to create a |
||||
// resource, but may not be changed thereafter. |
||||
IMMUTABLE = 5; |
||||
} |
||||
|
||||
|
||||
extend google.protobuf.FieldOptions { |
||||
// A designation of a specific field behavior (required, output only, etc.) |
||||
// in protobuf messages. |
||||
// |
||||
// Examples: |
||||
// |
||||
// string name = 1 [(google.api.field_behavior) = REQUIRED]; |
||||
// State state = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; |
||||
// google.protobuf.Duration ttl = 1 |
||||
// [(google.api.field_behavior) = INPUT_ONLY]; |
||||
// google.protobuf.Timestamp expire_time = 1 |
||||
// [(google.api.field_behavior) = OUTPUT_ONLY, |
||||
// (google.api.field_behavior) = IMMUTABLE]; |
||||
repeated FieldBehavior field_behavior = 1052; |
||||
} |
Loading…
Reference in new issue