[SOLR-16380] Add OpenAPI decoration to v2 APIs

• Type: Improvement
• Status: Open
• Priority: Major
• Resolution: Unresolved
• Affects Version/s: main (10.0)
• Component/s: v2 API
• Assignee: Unassigned
• Reporter: Jason Gerlowski
• Created: 02/Sep/22 10:07
• Updated: 06/Aug/24 14:53

Description

SOLR-16346 introduces (or will introduce) a build integration that generates an OpenAPI spec covering Solr's v2 APIs. This spec can then be used with other tooling to do cool things, like generate bindings and clients for various programming languages.

Converting our v2 APIs to JAX-RS will ensure each API some fundamental coverage in the OpenAPI spec. But this won't put any information in the spec about what each API input "does", or what each output "means" in a response from Solr. To make our spec (and thus our generated clients) more useful, we should decorate each JAX-RS API with OpenAPI annotations that document the API overall and describe its inputs and outputs. This will make our generated clients much easier to use. (We should ensure that this is done in a way that avoids duplication of this information in the ref-guide, perhaps making use of the OpenAPI tooling's asciidoctor generator to populate sections of the ref-guide at build time.)

This ticket aims to be an umbrella for adding this OpenAPI "decoration": PRs for individual APIs or groups of APIs can be handled by specific subtasks.

Issue Links

• is a child of: SOLR-15734 Prepare v2 API for v1 deprecation, eventual removal
• relates to: SOLR-17395 Generate v2 API ref-guide content from OpenAPI Spec

Sub-Tasks

• Add OpenAPI annotations to v2 Cluster, ClusterProp APIs: Open
• Add OpenAPI annotations to v2 collection, coll-prop, and status APIs: Open
• Add OpenAPI annotations to v2 shard, replica, and replica-prop CRUD APIs: Open
• Add OpenAPI annotations to v2 alias and alias-prop CRUD APIs: Open
• Add OpenAPI annotations to v2 snapshot and backup APIs: Open
• Add OpenAPI annotations to v2 schema APIs: Open
• Add OpenAPI annotations to v2 config APIs: Open
• Add OpenAPI annotations to v2 "per-core" APIs: Open
• Add OpenAPI annotations to miscellaneous v2 coll/core APIs: Open