mirror of https://github.com/prometheus/prometheus
471 lines
19 KiB
Protocol Buffer
471 lines
19 KiB
Protocol Buffer
syntax = "proto3";
|
|
|
|
package grpc.gateway.protoc_gen_swagger.options;
|
|
|
|
option go_package = "github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger/options";
|
|
|
|
import "google/protobuf/any.proto";
|
|
import "google/protobuf/struct.proto";
|
|
|
|
// `Swagger` is a representation of OpenAPI v2 specification's Swagger object.
|
|
//
|
|
// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#swaggerObject
|
|
//
|
|
message Swagger {
|
|
// Specifies the Swagger Specification version being used. It can be
|
|
// used by the Swagger UI and other clients to interpret the API listing. The
|
|
// value MUST be "2.0".
|
|
string swagger = 1;
|
|
// Provides metadata about the API. The metadata can be used by the
|
|
// clients if needed.
|
|
Info info = 2;
|
|
// The host (name or ip) serving the API. This MUST be the host only and does
|
|
// not include the scheme nor sub-paths. It MAY include a port. If the host is
|
|
// not included, the host serving the documentation is to be used (including
|
|
// the port). The host does not support path templating.
|
|
string host = 3;
|
|
// The base path on which the API is served, which is relative to the host. If
|
|
// it is not included, the API is served directly under the host. The value
|
|
// MUST start with a leading slash (/). The basePath does not support path
|
|
// templating.
|
|
// Note that using `base_path` does not change the endpoint paths that are
|
|
// generated in the resulting Swagger file. If you wish to use `base_path`
|
|
// with relatively generated Swagger paths, the `base_path` prefix must be
|
|
// manually removed from your `google.api.http` paths and your code changed to
|
|
// serve the API from the `base_path`.
|
|
string base_path = 4;
|
|
enum SwaggerScheme {
|
|
UNKNOWN = 0;
|
|
HTTP = 1;
|
|
HTTPS = 2;
|
|
WS = 3;
|
|
WSS = 4;
|
|
}
|
|
// The transfer protocol of the API. Values MUST be from the list: "http",
|
|
// "https", "ws", "wss". If the schemes is not included, the default scheme to
|
|
// be used is the one used to access the Swagger definition itself.
|
|
repeated SwaggerScheme schemes = 5;
|
|
// A list of MIME types the APIs can consume. This is global to all APIs but
|
|
// can be overridden on specific API calls. Value MUST be as described under
|
|
// Mime Types.
|
|
repeated string consumes = 6;
|
|
// A list of MIME types the APIs can produce. This is global to all APIs but
|
|
// can be overridden on specific API calls. Value MUST be as described under
|
|
// Mime Types.
|
|
repeated string produces = 7;
|
|
// field 8 is reserved for 'paths'.
|
|
reserved 8;
|
|
// field 9 is reserved for 'definitions', which at this time are already
|
|
// exposed as and customizable as proto messages.
|
|
reserved 9;
|
|
// An object to hold responses that can be used across operations. This
|
|
// property does not define global responses for all operations.
|
|
map<string, Response> responses = 10;
|
|
// Security scheme definitions that can be used across the specification.
|
|
SecurityDefinitions security_definitions = 11;
|
|
// A declaration of which security schemes are applied for the API as a whole.
|
|
// The list of values describes alternative security schemes that can be used
|
|
// (that is, there is a logical OR between the security requirements).
|
|
// Individual operations can override this definition.
|
|
repeated SecurityRequirement security = 12;
|
|
// field 13 is reserved for 'tags', which are supposed to be exposed as and
|
|
// customizable as proto services. TODO(ivucica): add processing of proto
|
|
// service objects into OpenAPI v2 Tag objects.
|
|
reserved 13;
|
|
// Additional external documentation.
|
|
ExternalDocumentation external_docs = 14;
|
|
map<string, google.protobuf.Value> extensions = 15;
|
|
}
|
|
|
|
// `Operation` is a representation of OpenAPI v2 specification's Operation object.
|
|
//
|
|
// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#operationObject
|
|
//
|
|
message Operation {
|
|
// A list of tags for API documentation control. Tags can be used for logical
|
|
// grouping of operations by resources or any other qualifier.
|
|
repeated string tags = 1;
|
|
// A short summary of what the operation does. For maximum readability in the
|
|
// swagger-ui, this field SHOULD be less than 120 characters.
|
|
string summary = 2;
|
|
// A verbose explanation of the operation behavior. GFM syntax can be used for
|
|
// rich text representation.
|
|
string description = 3;
|
|
// Additional external documentation for this operation.
|
|
ExternalDocumentation external_docs = 4;
|
|
// Unique string used to identify the operation. The id MUST be unique among
|
|
// all operations described in the API. Tools and libraries MAY use the
|
|
// operationId to uniquely identify an operation, therefore, it is recommended
|
|
// to follow common programming naming conventions.
|
|
string operation_id = 5;
|
|
// A list of MIME types the operation can consume. This overrides the consumes
|
|
// definition at the Swagger Object. An empty value MAY be used to clear the
|
|
// global definition. Value MUST be as described under Mime Types.
|
|
repeated string consumes = 6;
|
|
// A list of MIME types the operation can produce. This overrides the produces
|
|
// definition at the Swagger Object. An empty value MAY be used to clear the
|
|
// global definition. Value MUST be as described under Mime Types.
|
|
repeated string produces = 7;
|
|
// field 8 is reserved for 'parameters'.
|
|
reserved 8;
|
|
// The list of possible responses as they are returned from executing this
|
|
// operation.
|
|
map<string, Response> responses = 9;
|
|
// The transfer protocol for the operation. Values MUST be from the list:
|
|
// "http", "https", "ws", "wss". The value overrides the Swagger Object
|
|
// schemes definition.
|
|
repeated string schemes = 10;
|
|
// Declares this operation to be deprecated. Usage of the declared operation
|
|
// should be refrained. Default value is false.
|
|
bool deprecated = 11;
|
|
// A declaration of which security schemes are applied for this operation. The
|
|
// list of values describes alternative security schemes that can be used
|
|
// (that is, there is a logical OR between the security requirements). This
|
|
// definition overrides any declared top-level security. To remove a top-level
|
|
// security declaration, an empty array can be used.
|
|
repeated SecurityRequirement security = 12;
|
|
map<string, google.protobuf.Value> extensions = 13;
|
|
}
|
|
|
|
// `Response` is a representation of OpenAPI v2 specification's Response object.
|
|
//
|
|
// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#responseObject
|
|
//
|
|
message Response {
|
|
// `Description` is a short description of the response.
|
|
// GFM syntax can be used for rich text representation.
|
|
string description = 1;
|
|
// `Schema` optionally defines the structure of the response.
|
|
// If `Schema` is not provided, it means there is no content to the response.
|
|
Schema schema = 2;
|
|
// field 3 is reserved for 'headers'.
|
|
reserved 3;
|
|
// `Examples` gives per-mimetype response examples.
|
|
// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#example-object
|
|
map<string, string> examples = 4;
|
|
map<string, google.protobuf.Value> extensions = 5;
|
|
}
|
|
|
|
// `Info` is a representation of OpenAPI v2 specification's Info object.
|
|
//
|
|
// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#infoObject
|
|
//
|
|
message Info {
|
|
// The title of the application.
|
|
string title = 1;
|
|
// A short description of the application. GFM syntax can be used for rich
|
|
// text representation.
|
|
string description = 2;
|
|
// The Terms of Service for the API.
|
|
string terms_of_service = 3;
|
|
// The contact information for the exposed API.
|
|
Contact contact = 4;
|
|
// The license information for the exposed API.
|
|
License license = 5;
|
|
// Provides the version of the application API (not to be confused
|
|
// with the specification version).
|
|
string version = 6;
|
|
map<string, google.protobuf.Value> extensions = 7;
|
|
}
|
|
|
|
// `Contact` is a representation of OpenAPI v2 specification's Contact object.
|
|
//
|
|
// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#contactObject
|
|
//
|
|
message Contact {
|
|
// The identifying name of the contact person/organization.
|
|
string name = 1;
|
|
// The URL pointing to the contact information. MUST be in the format of a
|
|
// URL.
|
|
string url = 2;
|
|
// The email address of the contact person/organization. MUST be in the format
|
|
// of an email address.
|
|
string email = 3;
|
|
}
|
|
|
|
// `License` is a representation of OpenAPI v2 specification's License object.
|
|
//
|
|
// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#licenseObject
|
|
//
|
|
message License {
|
|
// The license name used for the API.
|
|
string name = 1;
|
|
// A URL to the license used for the API. MUST be in the format of a URL.
|
|
string url = 2;
|
|
}
|
|
|
|
// `ExternalDocumentation` is a representation of OpenAPI v2 specification's
|
|
// ExternalDocumentation object.
|
|
//
|
|
// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#externalDocumentationObject
|
|
//
|
|
message ExternalDocumentation {
|
|
// A short description of the target documentation. GFM syntax can be used for
|
|
// rich text representation.
|
|
string description = 1;
|
|
// The URL for the target documentation. Value MUST be in the format
|
|
// of a URL.
|
|
string url = 2;
|
|
}
|
|
|
|
// `Schema` is a representation of OpenAPI v2 specification's Schema object.
|
|
//
|
|
// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#schemaObject
|
|
//
|
|
message Schema {
|
|
JSONSchema json_schema = 1;
|
|
// Adds support for polymorphism. The discriminator is the schema property
|
|
// name that is used to differentiate between other schema that inherit this
|
|
// schema. The property name used MUST be defined at this schema and it MUST
|
|
// be in the required property list. When used, the value MUST be the name of
|
|
// this schema or any schema that inherits it.
|
|
string discriminator = 2;
|
|
// Relevant only for Schema "properties" definitions. Declares the property as
|
|
// "read only". This means that it MAY be sent as part of a response but MUST
|
|
// NOT be sent as part of the request. Properties marked as readOnly being
|
|
// true SHOULD NOT be in the required list of the defined schema. Default
|
|
// value is false.
|
|
bool read_only = 3;
|
|
// field 4 is reserved for 'xml'.
|
|
reserved 4;
|
|
// Additional external documentation for this schema.
|
|
ExternalDocumentation external_docs = 5;
|
|
// A free-form property to include an example of an instance for this schema.
|
|
google.protobuf.Any example = 6;
|
|
}
|
|
|
|
// `JSONSchema` represents properties from JSON Schema taken, and as used, in
|
|
// the OpenAPI v2 spec.
|
|
//
|
|
// This includes changes made by OpenAPI v2.
|
|
//
|
|
// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#schemaObject
|
|
//
|
|
// See also: https://cswr.github.io/JsonSchema/spec/basic_types/,
|
|
// https://github.com/json-schema-org/json-schema-spec/blob/master/schema.json
|
|
//
|
|
// TODO(ivucica): document fields
|
|
message JSONSchema {
|
|
// field 1 is reserved for '$id', omitted from OpenAPI v2.
|
|
reserved 1;
|
|
// field 2 is reserved for '$schema', omitted from OpenAPI v2.
|
|
reserved 2;
|
|
// Ref is used to define an external reference to include in the message.
|
|
// This could be a fully qualified proto message reference, and that type must
|
|
// be imported into the protofile. If no message is identified, the Ref will
|
|
// be used verbatim in the output.
|
|
// For example:
|
|
// `ref: ".google.protobuf.Timestamp"`.
|
|
string ref = 3;
|
|
// field 4 is reserved for '$comment', omitted from OpenAPI v2.
|
|
reserved 4;
|
|
// The title of the schema.
|
|
string title = 5;
|
|
// A short description of the schema.
|
|
string description = 6;
|
|
string default = 7;
|
|
bool read_only = 8;
|
|
// field 9 is reserved for 'examples', which is omitted from OpenAPI v2 in
|
|
// favor of 'example' field.
|
|
reserved 9;
|
|
double multiple_of = 10;
|
|
// Maximum represents an inclusive upper limit for a numeric instance. The
|
|
// value of MUST be a number,
|
|
double maximum = 11;
|
|
bool exclusive_maximum = 12;
|
|
// minimum represents an inclusive lower limit for a numeric instance. The
|
|
// value of MUST be a number,
|
|
double minimum = 13;
|
|
bool exclusive_minimum = 14;
|
|
uint64 max_length = 15;
|
|
uint64 min_length = 16;
|
|
string pattern = 17;
|
|
// field 18 is reserved for 'additionalItems', omitted from OpenAPI v2.
|
|
reserved 18;
|
|
// field 19 is reserved for 'items', but in OpenAPI-specific way.
|
|
// TODO(ivucica): add 'items'?
|
|
reserved 19;
|
|
uint64 max_items = 20;
|
|
uint64 min_items = 21;
|
|
bool unique_items = 22;
|
|
// field 23 is reserved for 'contains', omitted from OpenAPI v2.
|
|
reserved 23;
|
|
uint64 max_properties = 24;
|
|
uint64 min_properties = 25;
|
|
repeated string required = 26;
|
|
// field 27 is reserved for 'additionalProperties', but in OpenAPI-specific
|
|
// way. TODO(ivucica): add 'additionalProperties'?
|
|
reserved 27;
|
|
// field 28 is reserved for 'definitions', omitted from OpenAPI v2.
|
|
reserved 28;
|
|
// field 29 is reserved for 'properties', but in OpenAPI-specific way.
|
|
// TODO(ivucica): add 'additionalProperties'?
|
|
reserved 29;
|
|
// following fields are reserved, as the properties have been omitted from
|
|
// OpenAPI v2:
|
|
// patternProperties, dependencies, propertyNames, const
|
|
reserved 30 to 33;
|
|
// Items in 'array' must be unique.
|
|
repeated string array = 34;
|
|
|
|
enum JSONSchemaSimpleTypes {
|
|
UNKNOWN = 0;
|
|
ARRAY = 1;
|
|
BOOLEAN = 2;
|
|
INTEGER = 3;
|
|
NULL = 4;
|
|
NUMBER = 5;
|
|
OBJECT = 6;
|
|
STRING = 7;
|
|
}
|
|
|
|
repeated JSONSchemaSimpleTypes type = 35;
|
|
// following fields are reserved, as the properties have been omitted from
|
|
// OpenAPI v2: format, contentMediaType, contentEncoding, if, then, else
|
|
reserved 36 to 41;
|
|
// field 42 is reserved for 'allOf', but in OpenAPI-specific way.
|
|
// TODO(ivucica): add 'allOf'?
|
|
reserved 42;
|
|
// following fields are reserved, as the properties have been omitted from
|
|
// OpenAPI v2:
|
|
// anyOf, oneOf, not
|
|
reserved 43 to 45;
|
|
}
|
|
|
|
// `Tag` is a representation of OpenAPI v2 specification's Tag object.
|
|
//
|
|
// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#tagObject
|
|
//
|
|
message Tag {
|
|
// field 1 is reserved for 'name'. In our generator, this is (to be) extracted
|
|
// from the name of proto service, and thus not exposed to the user, as
|
|
// changing tag object's name would break the link to the references to the
|
|
// tag in individual operation specifications.
|
|
//
|
|
// TODO(ivucica): Add 'name' property. Use it to allow override of the name of
|
|
// global Tag object, then use that name to reference the tag throughout the
|
|
// Swagger file.
|
|
reserved 1;
|
|
// A short description for the tag. GFM syntax can be used for rich text
|
|
// representation.
|
|
string description = 2;
|
|
// Additional external documentation for this tag.
|
|
ExternalDocumentation external_docs = 3;
|
|
}
|
|
|
|
// `SecurityDefinitions` is a representation of OpenAPI v2 specification's
|
|
// Security Definitions object.
|
|
//
|
|
// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#securityDefinitionsObject
|
|
//
|
|
// A declaration of the security schemes available to be used in the
|
|
// specification. This does not enforce the security schemes on the operations
|
|
// and only serves to provide the relevant details for each scheme.
|
|
message SecurityDefinitions {
|
|
// A single security scheme definition, mapping a "name" to the scheme it
|
|
// defines.
|
|
map<string, SecurityScheme> security = 1;
|
|
}
|
|
|
|
// `SecurityScheme` is a representation of OpenAPI v2 specification's
|
|
// Security Scheme object.
|
|
//
|
|
// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#securitySchemeObject
|
|
//
|
|
// Allows the definition of a security scheme that can be used by the
|
|
// operations. Supported schemes are basic authentication, an API key (either as
|
|
// a header or as a query parameter) and OAuth2's common flows (implicit,
|
|
// password, application and access code).
|
|
message SecurityScheme {
|
|
// The type of the security scheme. Valid values are "basic",
|
|
// "apiKey" or "oauth2".
|
|
enum Type {
|
|
TYPE_INVALID = 0;
|
|
TYPE_BASIC = 1;
|
|
TYPE_API_KEY = 2;
|
|
TYPE_OAUTH2 = 3;
|
|
}
|
|
|
|
// The location of the API key. Valid values are "query" or "header".
|
|
enum In {
|
|
IN_INVALID = 0;
|
|
IN_QUERY = 1;
|
|
IN_HEADER = 2;
|
|
}
|
|
|
|
// The flow used by the OAuth2 security scheme. Valid values are
|
|
// "implicit", "password", "application" or "accessCode".
|
|
enum Flow {
|
|
FLOW_INVALID = 0;
|
|
FLOW_IMPLICIT = 1;
|
|
FLOW_PASSWORD = 2;
|
|
FLOW_APPLICATION = 3;
|
|
FLOW_ACCESS_CODE = 4;
|
|
}
|
|
|
|
// The type of the security scheme. Valid values are "basic",
|
|
// "apiKey" or "oauth2".
|
|
Type type = 1;
|
|
// A short description for security scheme.
|
|
string description = 2;
|
|
// The name of the header or query parameter to be used.
|
|
// Valid for apiKey.
|
|
string name = 3;
|
|
// The location of the API key. Valid values are "query" or
|
|
// "header".
|
|
// Valid for apiKey.
|
|
In in = 4;
|
|
// The flow used by the OAuth2 security scheme. Valid values are
|
|
// "implicit", "password", "application" or "accessCode".
|
|
// Valid for oauth2.
|
|
Flow flow = 5;
|
|
// The authorization URL to be used for this flow. This SHOULD be in
|
|
// the form of a URL.
|
|
// Valid for oauth2/implicit and oauth2/accessCode.
|
|
string authorization_url = 6;
|
|
// The token URL to be used for this flow. This SHOULD be in the
|
|
// form of a URL.
|
|
// Valid for oauth2/password, oauth2/application and oauth2/accessCode.
|
|
string token_url = 7;
|
|
// The available scopes for the OAuth2 security scheme.
|
|
// Valid for oauth2.
|
|
Scopes scopes = 8;
|
|
map<string, google.protobuf.Value> extensions = 9;
|
|
}
|
|
|
|
// `SecurityRequirement` is a representation of OpenAPI v2 specification's
|
|
// Security Requirement object.
|
|
//
|
|
// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#securityRequirementObject
|
|
//
|
|
// Lists the required security schemes to execute this operation. The object can
|
|
// have multiple security schemes declared in it which are all required (that
|
|
// is, there is a logical AND between the schemes).
|
|
//
|
|
// The name used for each property MUST correspond to a security scheme
|
|
// declared in the Security Definitions.
|
|
message SecurityRequirement {
|
|
// If the security scheme is of type "oauth2", then the value is a list of
|
|
// scope names required for the execution. For other security scheme types,
|
|
// the array MUST be empty.
|
|
message SecurityRequirementValue {
|
|
repeated string scope = 1;
|
|
}
|
|
// Each name must correspond to a security scheme which is declared in
|
|
// the Security Definitions. If the security scheme is of type "oauth2",
|
|
// then the value is a list of scope names required for the execution.
|
|
// For other security scheme types, the array MUST be empty.
|
|
map<string, SecurityRequirementValue> security_requirement = 1;
|
|
}
|
|
|
|
// `Scopes` is a representation of OpenAPI v2 specification's Scopes object.
|
|
//
|
|
// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#scopesObject
|
|
//
|
|
// Lists the available scopes for an OAuth2 security scheme.
|
|
message Scopes {
|
|
// Maps between a name of a scope to a short description of it (as the value
|
|
// of the property).
|
|
map<string, string> scope = 1;
|
|
}
|