ApiHug Spring API Extension

What It Exposes

it-common-spring-api serves the metadata generated from proto contracts. It does not build API documentation through runtime reflection. Instead, it exposes the generated resources directly.

The main endpoints are:

OpenAPI document: /v3/api-docs
versioned OpenAPI documents: /v3/api-docs/{version} and /v3/api-docs/{version}.yaml
metadata endpoints:
- /hope/meta/errors
- /hope/meta/dictionaries
- /hope/meta/authorities
- /hope/meta/versions

/v3/api-docs is an OpenAPI 3 document. It is not Swagger 2.0 output.

Configuration

The configuration prefix is hope.api.

Property	Default	Meaning
`hope.api.enable`	`true`	Enable or disable the OpenAPI endpoint
`hope.api.path`	`/v3/api-docs`	Main OpenAPI route
`hope.api.showMeta`	`true`	Expose metadata endpoints
`hope.api.showActuator`	`false`	Show actuator endpoints in the API surface
`hope.api.project.name`	-	Bound proto project name
`hope.api.project.latest`	`true`	Serve the latest generated version
`hope.api.mcp.mcpServer`	`openapi-server`	MCP server name
`hope.api.mcp.toolPrefixName`	`""`	MCP tool name prefix
`hope.api.mcp.serverUrl`	-	Runtime base URL for MCP/OpenAPI integration

Example:

YAML

hope:
  api:
    enable: true
    path: /v3/api-docs
    show-meta: true
    project:
      name: my-api-proto

Runtime Model

ApiHug uses generated resources on the classpath. The API document, error dictionary, authority list, dictionary list, and versions list are all produced from the contract build output and then exposed by Spring MVC or WebFlux resources.

That means:

startup is fast because no runtime scanning is required
output is stable because it comes from the same generated contract artifacts
changing API metadata requires rebuilding the contract module, not mutating server annotations at runtime

Typical Startup Output

Text

Application 'demo-app' is running! Access URLs:

Local                             http://localhost:18089/
External                          http://192.168.0.115:18089/
OAS                               http://192.168.0.115:18089/v3/api-docs
Actuator                          http://192.168.0.115:18089/management
Api-Errors                        http://192.168.0.115:18089/hope/meta/errors
Api-Dictionaries                  http://192.168.0.115:18089/hope/meta/dictionaries
Api-Authorities                   http://192.168.0.115:18089/hope/meta/authorities
Api-Versions                      http://192.168.0.115:18089/hope/meta/versions
Profile(s)                        dev

Endpoint Summary

Route	Meaning
`/v3/api-docs`	Latest OpenAPI JSON
`/v3/api-docs.yaml`	Latest OpenAPI YAML
`/v3/api-docs/{version}`	Version-specific OpenAPI JSON
`/v3/api-docs/{version}.yaml`	Version-specific OpenAPI YAML
`/hope/meta/errors`	Domain error catalog
`/hope/meta/dictionaries`	Dictionary and constant metadata
`/hope/meta/authorities`	Authority metadata
`/hope/meta/versions`	Published API versions

Production Guidance

Disable hope.api.enable when the API document should not be public.
Disable hope.api.showMeta when metadata endpoints should remain private.
Keep the API surface tied to the contract build output so docs and runtime stay aligned.

References

it-common-spring-plus/it-common-spring-api/README.md
hope.common.spring.api.HopeApiProperties
hope.common.spring.api.resource.ApiMetaWebMvcResource
hope.common.spring.api.resource.ApiMetaWebFluxResource