syntax = "proto3";

package meshapi.gateway;

import "meshapi/gateway/gateway.proto";
import "meshapi/gateway/openapi/openapi.proto";

option go_package = "github.com/meshapi/grpc-api-gateway/api";

// OpenAPIServiceSpec defines configuration for generating OpenAPI documentation for gRPC services.
message OpenAPIServiceSpec {
	// selector is a dot-separated gRPC service method selector.
	//
	// If the selector begins with '~.', the current proto package will be added to the beginning
	// of the path. For instance: `~.MyService`. Since no proto package can be deduced in the global
	// config file, this alias cannot be used in the global config file.
	//
	// If the selector does not begin with '~.', it will be treated as a fully qualified method name (FQMN).
	string selector = 1;
	// document can be used to override default values for OpenAPI document files when using the option to generate
	// OpenAPI files per service.
	//
	// Additionally, this can be used to change documentation generation behavior such as default responses regardless
	// of the output generation mode.
	//
	// NOTE: This document will only be used when using output mode of "service" and in all other
	// modes, this object simply gets ignored save for the config field. Since the config field instructs
	// the generation of responses and the document objects for that service only, regardless of the output mode
	// the settings will be honored.
	gateway.openapi.Document document = 2;
	// methods maps each method to an operation configuration.
	map<string, gateway.openapi.Operation> methods = 3;
}

// OpenAPIMessageSpec defines configuration for generating OpenAPI documentation for protobuf messages.
message OpenAPIMessageSpec {
	// selector is a dot-separated protobuf message selector.
	//
	// If the selector begins with a '.', it will be treated as an absolute path.
	// If it begins with '~.', the current proto package will be added to the beginning
	// of the path. For instance: `~.MyMessage`. Since no proto package can be deduced in the global
	// config file, this alias cannot be used in the global config file.
	// If the path does not begin with a '.' or '~.', it will be treated as a relative path and a search
	// from the current proto package will be performed in order to find the message.
	string selector = 1;
	// schema controls the OpenAPI v3.1 schema generation for this proto message.
	gateway.openapi.Schema schema = 2;
	// fields allows controlling the OpenAPI v3.1 generation for individual fields in this proto message.
	map<string, gateway.openapi.Schema> fields = 3;
}

// OpenAPIEnumSpec defines configuration for generating OpenAPI documentation for protobuf enums.
message OpenAPIEnumSpec {
	// selector is a dot-separated protobuf enum selector.
	//
	// If the selector begins with a '.', it will be treated as an absolute path.
	// If it begins with '~.', the current proto package will be added to the beginning
	// of the path. For instance: `~.MyEnum`. Since no proto package can be deduced in the global
	// config file, this alias cannot be used in the global config file.
	// If the path does not begin with a '.' or '~.', it will be treated as a relative path and a search
	// from the current proto package will be performed in order to find the enum.
	string selector = 1;
	// schema controls the OpenAPI v3.1 schema generation for this proto enum.
	gateway.openapi.Schema schema = 2;
}

// OpenAPISpec defines the overall OpenAPI documentation configuration.
message OpenAPISpec {
	// Document is the OpenAPI v3.1 document configuration which controls how the OpenAPI documentation is generated.
	//
	// This document can be defined to define a base config for all documents (if in the global config) or the document
	// for the current output target. For instance, when using output mode of "service", each service defined in the
	// associated proto file inherits this base document and can additionally specify more defaults for its own OpenAPI
	// document. When defining this in the global config and for specific proto files, the configs get merged together
	// but the priority is given to the proto document.
	gateway.openapi.Document document = 1;

	// services is used to configure OpenAPI v3.1 output for gRPC services.
	repeated OpenAPIServiceSpec services = 2;

	// messages is used to configure OpenAPI v3.1 output for protobuf messages.
	repeated OpenAPIMessageSpec messages = 3;

	// enums is used to configure OpenAPI v3.1 output for protobuf enums.
	repeated OpenAPIEnumSpec enums = 4;
}

// Config is the content of a configuration file.
message Config {
	// gateway holds gateway configs.
	GatewaySpec gateway = 1;

	// openapi holds OpenAPI v3.1 configs.
	OpenAPISpec openapi = 2;
}
