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";

// `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
//
// TODO(ivucica): document fields
message Swagger {
  string swagger = 1;
  Info info = 2;
  string host = 3;
  string base_path = 4;
  enum SwaggerScheme {
    UNKNOWN = 0;
    HTTP = 1;
    HTTPS = 2;
    WS = 3;
    WSS = 4;
  }
  repeated SwaggerScheme schemes = 5;
  repeated string consumes = 6;
  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;
  // field 10 is reserved for 'responses'.
  reserved 10;
  // field 11 is reserved for 'securityDefinitions'.
  reserved 11;
  // field 12 is reserved for repeated 'security'.
  reserved 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;
  ExternalDocumentation external_docs = 14;
}

// `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
//
// TODO(ivucica): document fields
message Operation {
  repeated string tags = 1;
  string summary = 2;
  string description = 3;
  ExternalDocumentation external_docs = 4;
  string operation_id = 5;
  repeated string consumes = 6;
  repeated string produces = 7;
  // field 8 is reserved for 'parameters'.
  reserved 8;
  // field 9 is reserved for 'responses'.
  reserved 9;
  repeated string schemes = 10;
  bool deprecated = 11;
  // field 12 is reserved for 'security'.
  reserved 12;
  
}

// `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
//
// TODO(ivucica): document fields
message Info {
  string title = 1;
  string description = 2;
  string terms_of_service = 3;
  Contact contact = 4;
  // field 5 is reserved for 'license'.
  reserved 5;
  string version = 6;
}

// `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
//
// TODO(ivucica): document fields
message Contact {
  string name = 1;
  string url = 2;
  string email = 3;
}

// `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
//
// TODO(ivucica): document fields
message ExternalDocumentation {
  string description = 1;
  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
//
// TODO(ivucica): document fields
message Schema {
  JSONSchema json_schema = 1;
  string discriminator = 2;
  bool read_only = 3;
  // field 4 is reserved for 'xml'.
  reserved 4;
  ExternalDocumentation external_docs = 5;
  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;
  // field 3 is reserved for '$ref', although it is unclear how it would be used.
  reserved 3;
  // field 4 is reserved for '$comment', omitted from OpenAPI v2.
  reserved 4;
  string title = 5;
  string description = 6;
  string default = 7;
  // field 8 is reserved for 'readOnly', which has an OpenAPI v2-specific meaning and is defined there.
  reserved 8;
  // field 9 is reserved for 'examples', which is omitted from OpenAPI v2 in favor of 'example' field.
  reserved 9;
  double multiple_of = 10;
  double maximum = 11;
  bool exclusive_maximum = 12;
  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
//
// TODO(ivucica): document fields
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;
  // TODO(ivucica): Description should be extracted from comments on the proto
  // service object.
  string description = 2;
  ExternalDocumentation external_docs = 3;
}