[jira] [Created] (SOLR-16380) Add OpenAPI decoration to v2 APIs

["Jason Gerlowski (Jira)" <ji...@apache.org>]

Jason Gerlowski created SOLR-16380:
--------------------------------------

             Summary: Add OpenAPI decoration to v2 APIs
                 Key: SOLR-16380
                 URL: https://issues.apache.org/jira/browse/SOLR-16380
             Project: Solr
          Issue Type: Improvement
      Security Level: Public (Default Security Level. Issues are Public)
          Components: v2 API
    Affects Versions: main (10.0)
            Reporter: Jason Gerlowski


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. 



--
This message was sent by Atlassian Jira
(v8.20.10#820010)

---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org