[
https://issues.apache.org/jira/browse/SOLR-16346?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17581913#comment-17581913
]
Jason Gerlowski commented on SOLR-16346:
----------------------------------------
I spent some time recently [playing with this a
bit|https://github.com/gerlowskija/solr/tree/openapi-generation-spike]. That
branch has a gradle 'resolve' task generate the OpenAPI spec, and an
'openApiGenerate' task generate a Python client in turn. One v2 API
({{/node/logging}}) was updated with OpenAPI annotations.
In terms of difficulty, I was pleasantly surprised. I'm not a gradle expert by
any means, but the gradle integration seemed suspiciously straightforward.
It took a good bit more effort to take an existing v2 API and surround it with
the right annotations so that it was represented correctly in the generated
spec (and Python client). The plugin (swagger-core's
[swagger-gradle-plugin|blob/master/modules/swagger-gradle-plugin/README.md])
seems to be built with JAX-RS-style APIs in mind. By default, it treats method
inputs as API inputs, and return values as the response body. This default
doesn't work super well with the method signatures used in our current v2 API
framework; these defaults can all be overridden, but the annotations to do this
end up getting pretty verbose. Covering all our APIs would be much easier if
they were defined in JAX-RS (or at least using similar conventions). But of
course, it's all still possible as things are now.
> Generate (and use) OpenAPI spec for v2 APIs
> -------------------------------------------
>
> Key: SOLR-16346
> URL: https://issues.apache.org/jira/browse/SOLR-16346
> 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
> Priority: Major
>
> An integration with [OpenAPI|https://www.openapis.org/] and its tooling has a
> lot to offer Solr. Once generated, an OpenAPI specification can be used to:
> * [generate clients|https://github.com/OpenAPITools/openapi-generator] for
> multiple programming languages
> * power a web UI to document and help users craft API calls (e.g.
> [redoc|https://github.com/Redocly/redoc]
> * [detect breaking API changes|https://github.com/Azure/openapi-diff] across
> releases.
> Of course, these benefits are only useful if we take pains to document our
> API inputs and outputs (probably with annotations that live directly in our
> Java code). But I think there's enough upside to be worth that trouble.
> This ticket aims to cover integrating OpenAPI into our gradle build, so that
> a single task can be used to generate an OpenAPI spec. (It might also make
> sense to use this ticket to cover generating client bindings for one or more
> languages.)
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscr...@solr.apache.org
For additional commands, e-mail: issues-h...@solr.apache.org
