[SOLR-17395] Generate v2 API ref-guide content from OpenAPI Spec

• Type: Bug
• Status: Open
• Priority: Minor
• Resolution: Unresolved
• Component/s: documentation
• Assignee: Unassigned
• Reporter: Jason Gerlowski
• Created: 06/Aug/24 14:53
• Updated: 25/Sep/24 19:28

Description

SOLR-16346 created an OpenAPI specification (or "OAS") covering our v2 APIs, and we've since started to use this OAS to generate various other artifacts: Java bindings for SolrJ (SOLR-16825), a Python client (SOLR-16835), a Javascript client.

The same tooling used to produce the artifacts above can also be used to generate asciidoc content. We should investigate using this to generate content for our ref-guide.

This benefits will users by ensuring that the documentation they're reading is always up-to-date with any code changes. And it benefits us developers by giving us less content to maintain manually. (Developers will have to pay close attention to annotations in the code that ultimately drive the OAS. But that's probably easier than always remembering to update docs that live in some other part of the source tree entirely.)

Issue Links

• is related to: SOLR-16380 Add OpenAPI decoration to v2 APIs
• is related to: SOLR-16825 Generate Java bindings from OpenAPI spec