# Issue when generating Java client for Jira Cloud from OpenAPI specs

**URL:** <https://community.developer.atlassian.com/t/issue-when-generating-java-client-for-jira-cloud-from-openapi-specs/78760>\
**Category:** Jira Cloud\
**Tags:** open-api, jira-cloud, rest-api, java\
**Created:** [April 1, 2024, 6:28pm UTC](https://community.developer.atlassian.com/t/issue-when-generating-java-client-for-jira-cloud-from-openapi-specs/78760 "2024-04-01T18:28:16Z")\
**Posts on this page:** 8\
**Page:** 1

<div class="post-metadata">

**Author:** ![JoaoBrltYogi](https://sea1.discourse-cdn.com/atlassiandeveloper/user_avatar/community.developer.atlassian.com/joaobrltyogi/32/47000_2.png) [@JoaoBrltYogi](https://community.developer.atlassian.com/u/JoaoBrltYogi)\
**Post date:** [April 1, 2024, 6:28pm UTC](https://community.developer.atlassian.com/t/issue-when-generating-java-client-for-jira-cloud-from-openapi-specs/78760/1 "2024-04-01T18:28:16Z")

</div>

Hi everyone! 👋

We’re trying to generate a Java client to interact with the Jira Cloud REST API v3 using [OpenAPI generator](https://openapi-generator.tech/docs/plugins) and the provided [OpenAPI specifications](https://dac-static.atlassian.com/cloud/jira/platform/swagger-v3.v3.json).

However, we’re having a bit of trouble and were wondering if anyone else had encountered the same issues?

We are using the `java` generator and the `resttemplate` library.  
Here’s the configuration we use for the OpenAPI generator Maven plugin:

> **Maven configuration**
>
> ```xml
> <!-- OpenAPI generator plugin -->
> <plugin>
> <groupId>org.openapitools</groupId>
> <artifactId>openapi-generator-maven-plugin</artifactId>
> <version>${openapi-generator-maven-plugin.version}</version>
> <executions>
> <!-- Jira Rest API v3 -->
> <execution>
> <id>jira</id>
> <goals>
> <goal>generate</goal>
> </goals>
> <configuration>
> <inputSpec>${project.basedir}/src/main/resources/jira/openapi-jira-v3.v3.json</inputSpec>
> <!-- Generate a Java client -->
> <generatorName>java</generatorName>
> 
> <!-- Configure the output -->
> <output>${project.build.directory}/generated-sources</output>
> <apiPackage>${jira.package}.v3</apiPackage>
> <modelPackage>${jira.package}.v3.model</modelPackage>
> <invokerPackage>${jira.package}.v3.client</invokerPackage>
> 
> <!-- Configure the generated code -->
> <generateApis>true</generateApis>
> <generateModels>true</generateModels>
> <generateSupportingFiles>true</generateSupportingFiles>
> <generateModelTests>false</generateModelTests>
> <generateApiTests>false</generateApiTests>
> <generateModelDocumentation>true</generateModelDocumentation>
> <generateApiDocumentation>true</generateApiDocumentation>
> 
> <!-- Fix ambiguous imports -->
> <importMappings>
> <importMapping>Locale=java.util.Locale</importMapping>
> </importMappings>
> 
> <configOptions>
> <!-- Generate code for the RestTemplate -->
> <library>resttemplate</library>
> 
> <!-- Generate code for Spring Boot 3 -->
> <useSpringBoot3>true</useSpringBoot3>
> 
> <!-- Use jakarta.* instead of java.* imports -->
> <useJakartaEe>true</useJakartaEe>
> 
> <!-- Disable documentation annotations -->
> <annotationLibrary>none</annotationLibrary>
> 
> <!-- Disable OpenAPI documentation -->
> <documentationProvider>none</documentationProvider>
> 
> <!-- Disable OpenAPI Jackson nullable library -->
> <openApiNullable>false</openApiNullable>
> </configOptions>
> </configuration>
> </execution>
> 
> </executions>
> </plugin>
> 
> ```

First, we had an issue due to an ambiguous import of `Locale`.  
We managed to fix this using an import mapping to force the use of `java.util.Locale`.

Then, we had an issue with the `WorkflowCapabilities` schema.  
Indeed, OpenAPI generator seems to get confused and handles the `projectTypes` property as both an enum and an array:

> **Generated code**
>
> ```java
> public class WorkflowCapabilities {
> // [...]
>   
> private ProjectTypesEnum projectTypes;
>   
> // [...]
> 
> public WorkflowCapabilities addProjectTypesItem(ProjectTypesEnum projectTypesItem) {
> if (this.projectTypes == null) {
> this.projectTypes = new ArrayList<>();
> }
> this.projectTypes.add(projectTypesItem);
> return this;
> }
>   
> // [...]
> }
> 
> ```

We though this might be a bug in the OpenAPI generator.  
However, by checking the OpenAPI specifications, we found that the `projectTypes` property of the `WorkflowCapabilities` schema was indeed a bit ambiguous.  
Indeed, the `projectTypes` property is declared as an `array` of `enum` but also contains an `enum` attribute which leads the OpenAPI generator to think this property is both an array and an enum:

> **OpenAPI specifications**
>
> ```json
> "WorkflowCapabilities": {
> "additionalProperties": false,
> "properties": {
> // [...]
> "projectTypes": {
> "description": "The types of projects that this capability set is available for.",
> "enum": [
> "software",
> "service_desk",
> "product_discovery",
> "business",
> "unknown"
> ],
> "items": {
> "description": "The types of projects that this capability set is available for.",
> "enum": [
> "software",
> "service_desk",
> "product_discovery",
> "business",
> "unknown"
> ],
> "type": "string"
> },
> "type": "array"
> },
> // [...]
> },
> "type": "object"
> },
> 
> ```

For now, we managed to generate the Java client by manually updating the OpenAPI specifications and removing the `enum` attribute of the `projectType` property in the `WorkflowCapabilities` schema.  
However, this is of course not great for maintainability.  
We are considering contributing to OpenAPI generator to ignore the `enum` attribute if the type of a property is `array` or using a different OpenAPI generator library (but we need to use `RestTemplate`).

What are your thoughts on the subject?  
Do you have other solutions?  
Do you think it is a bug in the OpenAPI generator library?  
Do you think the OpenAPI specifications for the Jira Cloud REST API v3 should be updated? 😉

Cheers!

---

<div class="post-metadata">

**Author:** ![ibuchanan](https://sea1.discourse-cdn.com/atlassiandeveloper/user_avatar/community.developer.atlassian.com/ibuchanan/32/35815_2.png) [@ibuchanan](https://community.developer.atlassian.com/u/ibuchanan)\
**Post date:** [April 2, 2024, 1:36am UTC](https://community.developer.atlassian.com/t/issue-when-generating-java-client-for-jira-cloud-from-openapi-specs/78760/2 "2024-04-02T01:36:41Z")

</div>

@JoaoBrltYogi,

I’ve experimented a lot with Jira’s OpenAPI Spec, leaving me with the following opinions:

> [@JoaoBrltYogi](#):
>
> Do you have other solutions?

Yes. For Java, [Retrofit](https://square.github.io/retrofit/). Because it seems like bad architecture to bind to the entire API surface when you only use a part.

> [@JoaoBrltYogi](#):
>
> Do you think it is a bug in the OpenAPI generator library?

Yes and no. More precisely, I think general purpose libraries must make decisions about how to best support a range of APIs. I think it would be reasonable to expect to invest in customization for an API like Jira’s with so much history. To the extent that it might be preferable to have a Jira-specific generator. For example, I’d think any reasonable app would need to handle:

- Pagination: Jira isn’t exactly consistent across endpoints)
- Rate limiting: Jira doesn’t have fixed limits but headers to watch.
- Errors: There are cases where Jira returns errors in a 200 response. ☹

> [@JoaoBrltYogi](#):
>
> Do you think the OpenAPI specifications for the Jira Cloud REST API v3 should be updated?

Yes and no. More precisely, I know there are worse errors in Jira’s API spec. Again, with Jira’s long history, I think there are going to be some parts of the API that don’t fit neatly into OpenAPI Spec. There is going to be some “impedance mismatch”.

I don’t want to discourage your use of OpenAPI generation. That’s going to be a better approach than a hand-crafted SDK. But, I do want to point out some of the trickier bits for your awareness. Jira’s OpenAPI does not mean you can get an SDK without effort.

---

<div class="post-metadata">

**Author:** ![epehrson](https://sea1.discourse-cdn.com/atlassiandeveloper/user_avatar/community.developer.atlassian.com/epehrson/32/35813_2.png) [@epehrson](https://community.developer.atlassian.com/u/epehrson)\
**Post date:** [April 2, 2024, 9:23am UTC](https://community.developer.atlassian.com/t/issue-when-generating-java-client-for-jira-cloud-from-openapi-specs/78760/3 "2024-04-02T09:23:06Z")

</div>

> First, we had an issue due to an ambiguous import of `Locale` .

@JoaoBrltYogi I think this is normal. I recall having used `modelNamePrefix` or `modelNameSuffix` to work around it for other APIs. But we could potentially rename that schema if you think it’s a big problem.

> the `projectTypes` property is declared as an `array` of `enum` but also contains an `enum` attribute which leads the OpenAPI generator to think this property is both an array and an enum

This seems like a bug in our spec. Could you please [raise an issue](https://ecosystem.atlassian.net/servicedesk/customer/portal/34/group/106/create/567) for it? I don’t think it’s a case OpenAPI generator needs to handle.

---

<div class="post-metadata">

**Author:** ![JoaoBrltYogi](https://sea1.discourse-cdn.com/atlassiandeveloper/user_avatar/community.developer.atlassian.com/joaobrltyogi/32/47000_2.png) [@JoaoBrltYogi](https://community.developer.atlassian.com/u/JoaoBrltYogi)\
**Post date:** [April 2, 2024, 4:49pm UTC](https://community.developer.atlassian.com/t/issue-when-generating-java-client-for-jira-cloud-from-openapi-specs/78760/4 "2024-04-02T16:49:41Z")

</div>

Hi @ibuchanan!

> Yes. For Java, [Retrofit](https://square.github.io/retrofit/). Because it seems like bad architecture to bind to the entire API surface when you only use a part.

We didn’t know Retrofit, thanks for the suggestion. 👌

> Yes and no. More precisely, I think general purpose libraries must make decisions about how to best support a range of APIs. I think it would be reasonable to expect to invest in customization for an API like Jira’s with so much history. To the extent that it might be preferable to have a Jira-specific generator.

Indeed, we haven’t used the generated client enough to identify these issues yet.  
Thanks for raising awareness about these consistency issues, etc.

> Yes and no. More precisely, I know there are worse errors in Jira’s API spec. Again, with Jira’s long history, I think there are going to be some parts of the API that don’t fit neatly into OpenAPI Spec. There is going to be some “impedance mismatch”.

Yes, I feel like it’s normal for such a large REST API with several teams working on it.  
Indeed, this means our solution will probably need a lot of refinement to make sure we properly handle each request to the Jira REST API.  
To be honest, we were hoping to find an existing Java client in the wild but sadly it does not seem to be the case.

---

<div class="post-metadata">

**Author:** ![JoaoBrltYogi](https://sea1.discourse-cdn.com/atlassiandeveloper/user_avatar/community.developer.atlassian.com/joaobrltyogi/32/47000_2.png) [@JoaoBrltYogi](https://community.developer.atlassian.com/u/JoaoBrltYogi)\
**Post date:** [April 2, 2024, 4:57pm UTC](https://community.developer.atlassian.com/t/issue-when-generating-java-client-for-jira-cloud-from-openapi-specs/78760/5 "2024-04-02T16:57:56Z")

</div>

Hi @epehrson!

Thanks for the quick response.

> I think this is normal. I recall having used `modelNamePrefix` or `modelNameSuffix` to work around it for other APIs. But we could potentially rename that schema if you think it’s a big problem.

Yes, no problem for naming conflicts.  
They are pretty easy to fix using the configuration parameters of the OpenAPI generator. 👌

> This seems like a bug in our spec. Could you please [raise an issue](https://ecosystem.atlassian.net/servicedesk/customer/portal/34/group/106/create/567) for it? I don’t think it’s a case OpenAPI generator needs to handle.

Thanks for the suggestion.  
We just raised an issue with detailed information on the subject (ECOHELP-38089). 🤞

---

<div class="post-metadata">

**Author:** ![Dario\_B](https://avatars.discourse-cdn.com/v4/letter/d/9d8465/32.png) [@Dario\_B](https://community.developer.atlassian.com/u/Dario_B)\
**Post date:** [April 10, 2024, 2:16pm UTC](https://community.developer.atlassian.com/t/issue-when-generating-java-client-for-jira-cloud-from-openapi-specs/78760/6 "2024-04-10T14:16:00Z")

</div>

I have created below bug ticket to have this fixed:

- [ECO-234 - Problem with declaration of projectTypes property in OpenAPI spec for Jira](https://jira.atlassian.com/browse/ECO-234)

Anyone interested can set themselves as watchers so that they will be notified in case of any update/progress.

Cheers,  
Dario

---

<div class="post-metadata">

**Author:** ![kashev](https://sea1.discourse-cdn.com/atlassiandeveloper/user_avatar/community.developer.atlassian.com/kashev/32/43014_2.png) [@kashev](https://community.developer.atlassian.com/u/kashev)\
**Post date:** [December 13, 2024, 9:59pm UTC](https://community.developer.atlassian.com/t/issue-when-generating-java-client-for-jira-cloud-from-openapi-specs/78760/7 "2024-12-13T21:59:30Z")

</div>

> [@ibuchanan](#):
>
> Yes. For Java, [Retrofit](https://square.github.io/retrofit/). Because it seems like bad architecture to bind to the entire API surface when you only use a part.

I think one of the reasons people on CDAC keep ending up (trying) to use either `openapi-generator` or `swaggen-codegen` is because these are the only projects I can find that support creating code for Spring `RestTemplate`.

- If you want to make a Java app that you put on the Marketplace that talks to Jira or Confluence Cloud, [Atlassian suggests](https://developer.atlassian.com/cloud/jira/platform/connect-frameworks-and-tools/) their framework, [Atlassian Connect Spring Boot](https://bitbucket.org/atlassian/atlassian-connect-spring-boot/src). In my experience, you’d be crazy to not want to use this to get started, as it handles so much for you.
- In the docs for ACSB, they tell you to use `AtlassianHostRestClients` to make requests to the host product. It returns Spring `RestTemplate`.
- If one doesn’t use Spring `RestTemplate`, you’re on your own for authenticating requests - no help from the framework that Atlassian publishes. Grab the right shared secret on your own, roll your own JWT, etc.

@ibuchanan, how would one go about using Retrofit in an ACSB project? At least at first glance, the project seems incompatible with solving the practical design goals of:

- Using ACSB, the functionality that it provides with `AtlassianHostRestClients`
- Not wanting to write custom code for every host product API that one wants to use (e.g. I write my own DTO for a Jira Issue, I write my own DTO for a _list_ of Jira Issues, I write my own DTO for a project, etc, etc.).
  - I think this is a really common reason that people start to look into API client generation using the spec Atlassian provides.

---

<div class="post-metadata">

**Author:** ![ibuchanan](https://sea1.discourse-cdn.com/atlassiandeveloper/user_avatar/community.developer.atlassian.com/ibuchanan/32/35815_2.png) [@ibuchanan](https://community.developer.atlassian.com/u/ibuchanan)\
**Post date:** [December 16, 2024, 11:41am UTC](https://community.developer.atlassian.com/t/issue-when-generating-java-client-for-jira-cloud-from-openapi-specs/78760/8 "2024-12-16T11:41:44Z")

</div>

@kashev,

I follow your argument. Because the author did not mention Connect, or ACSB, I assumed (perhaps incorrectly) no Connect. In which case, no conflict because the auth would be API Tokens or OAuth 2.0, which are not supported by ACSB.

For Connect, I don’t know a better approach than `openapi-generator`. But I’ll stand by my concluding statement, “Jira’s OpenAPI does not mean you can get an SDK without effort”. Which is to say, be prepared to tailor the code generator and please report bugs in the OpenAPI spec to developer support.
