SOLR-16825: Migrate API definitions to submodule, pt 2 #1866
Conversation
Mustache templating is designed to generate simple HTML pages, and so by default it escapes input variables as necessary to exist in a HTML document. This, combined with the '<' and '>' characters used in Java generics, causes problems for us in code generation. To avoid this, this commit updates our template to use the "triple-brace" syntax in a number of places, which tells mustache to not do any special escaping of the templated values.
|
Is it possible to make the model classes static inner classes of the interfaces that use them? |
|
Kindof? That approach works fine as far as JAX-RS and Solr are concerned. In fact I'm sure you noticed it's how things were structured when these classes lived in 'core'. The problem is code-generation. As each SolrRequest class is being generated, it needs to be able to import the Java POJOs it relies on. And the SolrRequest-generation is using the OAS as its input, not the existing Java code directly - so it doesn't have access to information like Java fully-qualified class names as it's being processed. (openapi-generator has the ability to generate model POJOs for users, and handles imports much more gracefully in this case. We've decided not to generate models though, since they'd essentially duplicate the POJOs that we already have. The "import" problem is the main downside of that decision.) Right now we work around this limitation in our template by keeping things pretty simple in terms of imports - we essentially expect all POJOs to be in a single package without any static class nesting that'd change the import pattern. (see here and here) Anyway, this feels like a fixable problem to me if it's worth it to us to dig in. I spent a few hours tweaking the OpenAPI spec and |
|
Thanks for the explanation! In general it seems a little daunting to have them all separated and there, when it would be easier to work with them in the same place. Maybe it'll be worth it to look into sometime. Maybe it won't... But I'm not going to block you on it here. |
|
Sounds good; I'll merge this in for now and we can revisit later if needed. |
Extracting annotated interfaces for these APIs includes them in the SolrRequest- generation we now do in SolrJ.
https://issues.apache.org/jira/browse/SOLR-16825
Description
SOLR-16825 added a new gradle module, 'api', which holds v2 API definitions as interfaces. This allows us to generate an OAS (and SolrRequest implementations from that) as a part of the solrj build.
But these artifacts (the OAS and generated Java code), only cover the v2 APIs that have interfaces in the 'api' module. We need to extract interfaces to live in 'api' for each v2 API in 'core' that doesn't already have one.
Solution
This PR creates 'api' interfaces for a number of v2 APIs, allowing SolrRequest implementations to be generated for them. The following APIs are covered in this PR:
Tests
Manual inspection of the generated OAS and SolrRequest implementations.
Checklist
Please review the following and check all that apply:
mainbranch../gradlew check.