Protocol Buffers Option

ApiHug uses protobuf custom options as its contract layer. The important part is the actual extension registrations shipped in it-proto-extend, not generic examples from other protobuf ecosystems.

Descriptor Targets

Custom options are attached to protobuf descriptor types:

• google.protobuf.FileOptions
• google.protobuf.ServiceOptions
• google.protobuf.MethodOptions
• google.protobuf.MessageOptions
• google.protobuf.FieldOptions
• google.protobuf.EnumOptions
• google.protobuf.EnumValueOptions

The same field number can be reused on different descriptor types. That is why several ApiHug extensions share 1042 or 31143 without conflicting.

Current Extension Packages

OpenAPI / Swagger

Import:

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

Registered in swagger/annotations.proto:

Use these when defining HTTP paths, request and response metadata, validation rules, enum display metadata, and mock data.

Persistence / Entity

Import:

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

Registered in domain/annotations.proto:

Use these when mapping domain messages to database tables, columns, views, and Liquibase customization.

Enum / Error Metadata

Import:

import "apihug/protobuf/extend/constant.proto";

Registered in constant.proto:

Use this for business codes, localized labels, and structured error metadata on enum values.

Version Tracking

Import:

import "apihug/protobuf/extend/version.proto";

version.proto is deprecated, but it still exists in the source and should be understood when auditing older projects.

Minimal Example

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

import "apihug/protobuf/swagger/annotations.proto";
import "apihug/protobuf/domain/annotations.proto";
import "apihug/protobuf/extend/constant.proto";

service PetApi {
  option (hope.swagger.svc) = {
    path: "/pets";
    description: "Pet API";
  };

  rpc ListPets (PetQuery) returns (PetView) {
    option (hope.swagger.operation) = {
      get: "";
      description: "List pets";
    };
  }
}

message Pet {
  option (hope.persistence.table) = {
    name: "PET";
    description: "Pet table";
  };

  string name = 1 [(hope.persistence.column) = {
    name: "NAME";
    nullable: false;
    length: 64;
  }];
}

enum PetStatus {
  PET_STATUS_UNSPECIFIED = 0 [(hope.constant.field) = {
    code: 0;
    message: "unspecified";
    message2: "unspecified";
  }];
}

See Also

1. API Directive Specification
2. Database Directive Specification
3. Enum Type Specification
4. Version Change Specification