API Directive Specification

// Forbidden to use the following options (rely on default code generation configuration)
option java_package = "...";
option java_multiple_files = true;
option go_package = "...";

// Forbidden to reference domain layer entities
import "com/example/domain/entities/user.proto";  // Wrong!

message CreateUserRequest {
  UserEntity user = 1;  // Wrong!
}

// Allow referencing constant layer (infra/)
import "com/example/infra/settings/user_constant.proto";
// Allow referencing other API messages
import "com/example/api/common/response.proto";

message CreateUserRequest {
  string user_name = 1;  // Use basic types
  UserStatusEnum status = 2;  // Enums can be shared
  CommonResponse response = 3;  // API internal reference
}

import "apihug/protobuf/swagger/annotations.proto";

import "apihug/protobuf/mock/mock.proto";

service ServiceName {
  option (hope.swagger.svc) = {
    path: "/base_path";
    description: "Service description";
  };
}

syntax = "proto3";
package com.example.pet.service;

import "apihug/protobuf/swagger/annotations.proto";

service PetService {
  option (hope.swagger.svc) = {
    path: "/pet";
    description: "Pet Manager service";
  };

  rpc GetPet (...) returns (...) {
    // Method definition...
  }
}

rpc MethodName (RequestType) returns (ResponseType) {
  option (hope.swagger.operation) = {
    post: "/path";  // or get/put/patch/delete
    description: "Method description";
  };
}

option (hope.swagger.operation) = {
  get: "/pet/{id}";
};

rpc UploadMeta (OpenApiMetaUploadRequest) returns (google.protobuf.Empty) {
  option (hope.swagger.operation) = {
    post: "/upload-meta";
    description: "Open platform upload API metadata";
    tags: "open";
    group: TENANT;
    authorization: {
      low_limit_risky_mode: ANONYMOUS
    };
    priority: HIGH;
    consumes: "multipart/form-data";
  };
}

rpc ReturnPageable (Customer) returns (Pet) {
  option (hope.swagger.operation) = {
    post: "/batch-user-pet";
    pageable: true;
    description: "Return pageable data based on request";
    tags: "user";
    tags: "pet";
    request_name: "pet";
  };
}

rpc UpdateByPath (google.protobuf.Empty) returns (google.protobuf.Empty) {
  option (hope.swagger.operation) = {
    post: "/update-by-path/{user-id}/try-more/{user-name}";
    description: "Test two path parameters";
    tags: "other";
    parameters: {
      parameter: {
        name: "user-id";
        in: PATH;
        schema: {
          format: INTEGER;
          maximum: 12345
        };
      };
      parameter: {
        name: "user-name";
        in: PATH;
        schema: {
          format: STRING;
          empty: false;
          pattern: "^[A-Za-z0-9+_.-]+@(.+)$";
          max_length: 64
        };
      }
    }
  };
}

rpc PlaceOrder (google.protobuf.Empty) returns (PlaceOrderRequest) {
  option (hope.swagger.operation) = {
    post: "/place-order";
    description: "Place order operation";
    summary: "Place order detailed operation";
    tags: "user";
    tags: "pet";
    security: {
      security_requirement: {
        key: "jwt";
        value: {
          scope: "pet:read";
          scope: "pet:write";
        };
      }
    }
  };
}

option (hope.swagger.operation) = {
  post: "/register";
  request_schema: {
    title: "RegisterPayload";
    description: "Validated registration body";
  };
};

response_media_type: APPLICATION_PDF;

parameters: {
  parameter: {
    name: "user-id";
    in: QUERY;
    is_repeated: true;
    schema: {
      format: INTEGER;
      description: "user id";
    }
  };
}

authorization: {
  low_limit_risky_mode: ANONYMOUS  // or LOGIN / ACTIVE
}

authorization: {
  rbac: {
    roles: {
      roles: ["ROLE_ADMIN", "ROLE_USER"]
    };
    authorities: ["USER_CREATE", "USER_DELETE"];
    combinator: AND;  // or OR
  }
}

authorization: {
  expression: "hasRole('ADMIN') and #userId == authentication.principal.id"
}

questions: [
  "How to get user order list?",
  "Query the most recent page of order data"
];

message MessageName {
  option (hope.swagger.schema) = {
    json_schema: {
      title: "Object title";
      description: "Object description";
    };
  };
}

message PlaceOrderRequest {
  option (hope.swagger.schema) = {
    json_schema: {
      title: "PlaceOrder";
      description: "Place order request";
    };
    external_docs: {
      url: "https://example.com/order-design";
      description: "Order design detailed information"
    }
  };

  uint64 id = 1 [(hope.swagger.field) = {
    description: "Request ID";
    empty: false;
    maximum: 12345;
    example: "1111";
  }];
}

String → empty: false
String (no spaces) → blank: false
Number/Date → nullable: false
Collection → empty: false

max_length: 100;    // uint64
min_length: 1;
max_items: 50;      // collection element count
min_items: 1;
max_properties: 20; // object property count
min_properties: 1;

maximum: 12345;     // double
minimum: 1;
exclusive_maximum: true;  // open interval
exclusive_minimum: true;
multiple_of: 10;          // must be multiple

pattern: "^[A-Za-z0-9+_.-]+@(.+)$";  // regex
enum: ["PENDING", "APPROVED", "REJECTED"];

string owner_id = 1 [(hope.swagger.field) = {
  field_configuration: {
    path_param_name: "owner-id";
  };
}];

email: true;                // email validation
assert: true;               // must be true/false
digits_integer: 3;          // integer part digits
digits_fraction: 2;         // decimal part digits
decimal_max: "999.99";      // string form
decimal_min: "0.01";

string phone = 1 [(hope.swagger.field) = {
  description: "Phone number";
  mock: {
    nature: CN_PHONE
  };
}];

option (hope.swagger.operation) = {
  post: "/ping";
  mock: {
    nature: GUID
  };
};

empty: "false"  // String, wrong!
nullable: "true"
is_repeated: "false"

empty: false  // bool type
nullable: true
is_repeated: false

length: {value: 32}  // Old syntax!
max_length: {value: 100}
maximum: {value: 12345}

length: 32  // uint32
max_length: 100  // uint64
maximum: 12345  // double

optional bool pageable = 51;
optional bool raw = 52;

syntax = "proto3";
package com.example.pet.service;

import "com/example/pet/bean/request.proto";
import "swagger/annotations.proto";
import "google/protobuf/empty.proto";

service PetService {
  option (hope.swagger.svc) = {
    path: "/pet";
    description: "Pet management service";
  };

  rpc UploadFile (UploadRequest) returns (google.protobuf.Empty) {
    option (hope.swagger.operation) = {
      post: "/upload";
      description: "Upload pet photo";
      tags: "pet";
      consumes: "multipart/form-data";
      multipart: true;
      authorization: {
        low_limit_risky_mode: LOGIN
      };
    };
  };

  rpc ListPets (PetQueryRequest) returns (Pet) {
    option (hope.swagger.operation) = {
      post: "/list";
      description: "Paginated query pet list";
      tags: "pet";
      pageable: true;
      authorization: {
        rbac: {
          authorities: ["PET_VIEW"];
        }
      };
    };
  };

  rpc GetPetById (google.protobuf.Empty) returns (Pet) {
    option (hope.swagger.operation) = {
      get: "/pets/{id}";
      description: "Get pet details by ID";
      tags: "pet";
      parameters: {
        parameter: {
          name: "id";
          in: PATH;
          schema: {
            format: LONG;
            minimum: 1;
          };
        }
      };
      authorization: {
        low_limit_risky_mode: ANONYMOUS
      };
    };
  };

  rpc DeletePet (google.protobuf.Empty) returns (google.protobuf.Empty) {
    option (hope.swagger.operation) = {
      delete: "/pets/{id}";
      description: "Delete pet";
      tags: "pet";
      priority: HIGH;
      parameters: {
        parameter: {
          name: "id";
          in: PATH;
          schema: {
            format: LONG;
          };
        }
      };
      authorization: {
        rbac: {
          roles: {roles: ["ROLE_ADMIN"]};
          authorities: ["PET_DELETE"];
          combinator: AND;
        }
      };
    };
  };
}

syntax = "proto3";
package com.example.pet.bean;

import "swagger/annotations.proto";
import "com/example/pet/enumeration/constants.proto";

message PlaceOrderRequest {
  option (hope.swagger.schema) = {
    json_schema: {
      title: "PlaceOrderRequest";
      description: "Place order request object";
    };
  };

  uint64 id = 1 [(hope.swagger.field) = {
    description: "Request ID";
    empty: false;
    maximum: 12345;
    example: "1111";
  }];

  uint64 pet_id = 2 [(hope.swagger.field) = {
    description: "Pet ID";
    empty: false;
    minimum: 1;
    maximum: 999999;
    example: "1985";
  }];

  uint32 quantity = 3 [(hope.swagger.field) = {
    description: "Purchase quantity";
    empty: false;
    minimum: 1;
    maximum: 100;
    example: "5";
  }];

  com.example.pet.enumeration.OrderStatus order_status = 4 [(hope.swagger.field) = {
    description: "Order status";
  }];

  string ship_date = 5 [(hope.swagger.field) = {
    description: "Shipping date";
    example: "2023-12-25";
    date_format: ISO_LOCAL_DATE;
    time_constraint_type: FUTURE;
    empty: false;
  }];

  bool complete = 6 [(hope.swagger.field) = {
    description: "Is completed";
    example: "false";
  }];

  string phone = 7 [(hope.swagger.field) = {
    description: "Contact phone";
    example: "13800138000";
    pattern: "^1[3-9]\\d{9}$";
    mock: {nature: CN_PHONE};
  }];

  string email = 8 [(hope.swagger.field) = {
    description: "Contact email";
    email: true;
    empty: false;
    mock: {nature: EMAIL};
  }];

  string remark = 9 [(hope.swagger.field) = {
    description: "Remark";
    max_length: 500;
    mock: {
      chinese_rule: {
        type: SENTENCE;
        max: 50;
      }
    };
  }];
}

empty: "false"  // String
max_length: {value: 100}  // Old syntax
pageable: "false"  // String

empty: false  // bool type
max_length: 100  // uint64 type
pageable: true  // optional bool

Query single resource -> GET /resources/{id}
Query list -> GET /resources or POST /resources/search
Create resource -> POST /resources
Full update -> PUT /resources/{id}
Partial update -> PATCH /resources/{id}
Delete resource -> DELETE /resources/{id}

Resource collection -> /pets
Specific resource -> /pets/{id}
Sub-resource -> /pets/{id}/photos
Action -> /pets/{id}/activate
Complex query -> POST /pets/search

Public interface -> low_limit_risky_mode: ANONYMOUS
Login required -> low_limit_risky_mode: LOGIN
Role required -> rbac.roles
Permission required -> rbac.authorities
Complex rules -> rbac.combinator: AND

service ServiceName {
  option (hope.swagger.svc) = {
    path: "/path";
    description: "Description";
  };

  rpc MethodName (...) returns (...) {
    option (hope.swagger.operation) = {
      post: "/path";
      description: "Description";
    };
  }
}

option (hope.swagger.operation) = {
  post: "/path";
  description: "Description";
  tags: "tag";
  authorization: {
    low_limit_risky_mode: LOGIN
  };
};

string field_name = sequence [(hope.swagger.field) = {
  description: "Description";
  example: "Example";
  empty: false;
}];