You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@solr.apache.org by GitBox <gi...@apache.org> on 2022/09/19 15:54:19 UTC
[GitHub] [solr] gerlowskija opened a new pull request, #1024: SOLR-16346: Generate OpenAPI spec
gerlowskija opened a new pull request, #1024:
URL: https://github.com/apache/solr/pull/1024
# Description
Projects can derive a lot of value from an OpenAPI spec description of their APIs. OpenAPI specs can be used to generate documentation UIs, clients in a variety of languages, etc. But while Solr defines some of its APIs in a way that OpenAPI tooling understands (see SOLR-16347), we don't currently produce an OpenAPI spec for this tooling to use.
# Solution
This PR adds the 'swagger-gradle-plugin' to our gradle build, allowing developers (or CI) to generate a spec with a new 'resolve' task (`./gradlew solr:core:resolve`). The spec is created in the 'core' module's `build/generated/openapi` directory and can be used as-is with most OpenAPI tooling.
# Tests
No automated tests as this is a build-system change, though some manual testing of the 'resolve' task and the produced OpenAPI spec.
# Checklist
Please review the following and check all that apply:
- [x] I have reviewed the guidelines for [How to Contribute](https://wiki.apache.org/solr/HowToContribute) and my code conforms to the standards described there to the best of my ability.
- [x] I have created a Jira issue and added the issue ID to my pull request title.
- [x] I have given Solr maintainers [access](https://help.github.com/en/articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork) to contribute to my PR branch. (optional but recommended)
- [x] I have developed this patch against the `main` branch.
- [ ] I have run `./gradlew check`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
[GitHub] [solr] epugh commented on pull request #1024: SOLR-16346: Generate OpenAPI spec
Posted by GitBox <gi...@apache.org>.
epugh commented on PR #1024:
URL: https://github.com/apache/solr/pull/1024#issuecomment-1251478820
Just to get this out, I found the annotation tags from your spike ;-) With this, I can get output from redoc!
```
diff --git a/solr/core/src/java/org/apache/solr/handler/configsets/ListConfigSetsAPI.java b/solr/core/src/java/org/apache/solr/handler/configsets/ListConfigSetsAPI.java
index 978f290d763..16b74c5b4b9 100644
--- a/solr/core/src/java/org/apache/solr/handler/configsets/ListConfigSetsAPI.java
+++ b/solr/core/src/java/org/apache/solr/handler/configsets/ListConfigSetsAPI.java
@@ -19,7 +19,10 @@ package org.apache.solr.handler.configsets;
import static org.apache.solr.security.PermissionNameProvider.Name.CONFIG_READ_PERM;
import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.info.Info;
+import io.swagger.v3.oas.annotations.info.License;
import java.util.List;
import javax.inject.Inject;
import javax.ws.rs.GET;
@@ -37,6 +40,7 @@ import org.apache.solr.jersey.SolrJerseyResponse;
*
* <p>This API (GET /v2/cluster/configs) is analogous to the v1 /admin/configs?action=LIST command.
*/
+@OpenAPIDefinition(info = @Info(title = "Solr v2 API", description = "Some description", license = @License(name = "ASL 2.0"), version = "0.0.1"))
@Path("/cluster/configs")
public class ListConfigSetsAPI extends JerseyResource {
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
[GitHub] [solr] gerlowskija commented on pull request #1024: SOLR-16346: Generate OpenAPI spec
Posted by GitBox <gi...@apache.org>.
gerlowskija commented on PR #1024:
URL: https://github.com/apache/solr/pull/1024#issuecomment-1251260475
Hey, thanks for the quick review @epugh! Running tests on this now; assuming those look good I'll target to commit sometime towards the end of the week!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
[GitHub] [solr] risdenk commented on a diff in pull request #1024: SOLR-16346: Generate OpenAPI spec
Posted by GitBox <gi...@apache.org>.
risdenk commented on code in PR #1024:
URL: https://github.com/apache/solr/pull/1024#discussion_r976562154
##########
solr/core/src/java/org/apache/solr/util/SolrVersion.java:
##########
@@ -32,7 +32,7 @@ public final class SolrVersion implements Comparable<SolrVersion> {
private final Version version;
// This static variable should be bumped for each release
- private static final String LATEST_STRING = "10.0.0";
+ public static final String LATEST_STRING = "10.0.0";
/** This instance represents the current (latest) version of Solr. */
public static final SolrVersion LATEST = SolrVersion.valueOf(LATEST_STRING);
Review Comment:
Would it be better to just use `LATEST` since its already public? I know it would be converting back to string potentially but keeps the encapsulation that was here.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
[GitHub] [solr] gerlowskija commented on pull request #1024: SOLR-16346: Generate OpenAPI spec
Posted by GitBox <gi...@apache.org>.
gerlowskija commented on PR #1024:
URL: https://github.com/apache/solr/pull/1024#issuecomment-1252721361
Yeah - I noticed that metadata is missing without the `@OpenAPIDefinition`. For the spike I felt fine just tossing that annotation on a random resource class, but it doesn't _really_ belong there....there's absolutely no reason that whole-spec-metadata should be defined on any one "resource" file. I'll need to look into what the actual "right" place for this annotation is...
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
[GitHub] [solr] epugh commented on pull request #1024: SOLR-16346: Generate OpenAPI spec
Posted by GitBox <gi...@apache.org>.
epugh commented on PR #1024:
URL: https://github.com/apache/solr/pull/1024#issuecomment-1251224228
Was going to comment on the ant changes asking about them, but then read the nice message on f31614855fc735d324a268d681fec30820cd2f22 and learned why!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
[GitHub] [solr] epugh commented on pull request #1024: SOLR-16346: Generate OpenAPI spec
Posted by GitBox <gi...@apache.org>.
epugh commented on PR #1024:
URL: https://github.com/apache/solr/pull/1024#issuecomment-1254053831
> Morning @epugh - I ended up adding the additional metadata onto the `JerseyApplications` class, which seemed like a decent place for "overview" type info? Lmk what you think!
I looked and didn't see it, that is perfect!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
[GitHub] [solr] gerlowskija merged pull request #1024: SOLR-16346: Generate OpenAPI spec
Posted by GitBox <gi...@apache.org>.
gerlowskija merged PR #1024:
URL: https://github.com/apache/solr/pull/1024
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
[GitHub] [solr] epugh commented on pull request #1024: SOLR-16346: Generate OpenAPI spec
Posted by GitBox <gi...@apache.org>.
epugh commented on PR #1024:
URL: https://github.com/apache/solr/pull/1024#issuecomment-1251459578
We need this to let Redoc consume the file:
```
"info" : {
"title" : "Solr v2 API",
"description" : "Some description",
"license" : {
"name" : "ASL 2.0"
},
"version" : "0.0.1"
},
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
[GitHub] [solr] gerlowskija commented on pull request #1024: SOLR-16346: Generate OpenAPI spec
Posted by GitBox <gi...@apache.org>.
gerlowskija commented on PR #1024:
URL: https://github.com/apache/solr/pull/1024#issuecomment-1253762388
Morning @epugh - I ended up adding the additional metadata onto the `JerseyApplications` class, which seemed like a decent place for "overview" type info? Lmk what you think!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
[GitHub] [solr] gerlowskija commented on a diff in pull request #1024: SOLR-16346: Generate OpenAPI spec
Posted by GitBox <gi...@apache.org>.
gerlowskija commented on code in PR #1024:
URL: https://github.com/apache/solr/pull/1024#discussion_r976636464
##########
solr/core/src/java/org/apache/solr/util/SolrVersion.java:
##########
@@ -32,7 +32,7 @@ public final class SolrVersion implements Comparable<SolrVersion> {
private final Version version;
// This static variable should be bumped for each release
- private static final String LATEST_STRING = "10.0.0";
+ public static final String LATEST_STRING = "10.0.0";
/** This instance represents the current (latest) version of Solr. */
public static final SolrVersion LATEST = SolrVersion.valueOf(LATEST_STRING);
Review Comment:
I tried this initially, but since this is an annotation value we're specifying, the compiler complains: `Attribute value must be constant`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org