Skip to content

Commit ac075f0

Browse files
box-sdk-buildbox-sdk-build
committed
docs: Added migration guides for Swift (box/box-codegen#862)
1 parent c2de15b commit ac075f0

File tree

4 files changed

+841
-203
lines changed

4 files changed

+841
-203
lines changed

‎.codegen.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
{ "engineHash": "ed07967", "specHash": "fa34496", "version": "0.1.0" }
1+
{ "engineHash": "e415a23", "specHash": "fa34496", "version": "0.1.0" }

‎migration-guides/3.x.x to 4.x.x.md‎

Lines changed: 0 additions & 202 deletions
This file was deleted.

‎migration-guides/from-box-java-sdk-gen-v0-to-box-java-sdk-v10.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# Migration guide from beta release (v0.X.Y) of the `box-java-sdk-gen` to the v10 version of the `box-java-sdk`
2+
3+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5+
6+
- [Installation](#installation)
7+
- [How to migrate](#how-to-migrate)
8+
- [Maven](#maven)
9+
- [Gradle](#gradle)
10+
- [Union classes name changes](#union-classes-name-changes)
11+
- [How to migrate](#how-to-migrate-1)
12+
- [Removed unused models from schemas namespace](#removed-unused-models-from-schemas-namespace)
13+
- [How to migrate](#how-to-migrate-2)
14+
15+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
16+
17+
## Installation
18+
19+
In order to start using v10 version of the Box Java SDK, you need to change the dependency in your project.
20+
The artifact name has changed from `com.box:box-java-sdk-gen` to `com.box:box-java-sdk`.
21+
You also need to set the version to `10.0.0` or higher. You can find the latest version on [Maven Central](https://search.maven.org/artifact/com.box/box-java-sdk).
22+
23+
### How to migrate
24+
25+
#### Maven
26+
27+
To start using v10 version of Box Java SDK in your Maven project replace the dependency in your `pom.xml` file.
28+
29+
**Old (`box-java-sdk-gen-v0`)**
30+
31+
```xml
32+
<dependency>
33+
<groupId>com.box</groupId>
34+
<artifactId>box-java-sdk-gen</artifactId>
35+
<version>0.8.0</version>
36+
</dependency>
37+
```
38+
39+
**New (`box-java-sdk-v10`)**
40+
41+
```xml
42+
<dependency>
43+
<groupId>com.box</groupId>
44+
<artifactId>box-java-sdk</artifactId>
45+
<version>10.0.0</version>
46+
</dependency>
47+
```
48+
49+
#### Gradle
50+
51+
To start using v10 version of Box Java SDK in your Gradle project replace the dependency in your `build.gradle` file.
52+
53+
**Old (`box-java-sdk-gen-v0`)**
54+
55+
```groovy
56+
implementation 'com.box:box-java-sdk-gen:0.8.0'
57+
```
58+
59+
**New (`box-java-sdk-v10`)**
60+
61+
```groovy
62+
implementation 'com.box:box-java-sdk:10.0.0'
63+
```
64+
65+
## Union classes name changes
66+
67+
In the beta version of the `box-java-sdk-gen` our `OneOf` class names (representing unions from the OpenAPI specification)
68+
were fully auto-generated based on the included variants. This often resulted in overly long names that were difficult
69+
to work with in tools like Git. For example: `MetadataFieldFilterDateRangeOrMetadataFieldFilterFloatRangeOrArrayOfStringOrNumberOrString`.
70+
Additionally, every time the new variant was added to the `OneOf`, the class name itself changed.
71+
Starting in v10, the names of `OneOf` classes are defined directly in the specification. This ensures that they are meaningful, short, and stable over time.
72+
73+
### How to migrate
74+
75+
If your code references any of the renamed classes, replace the old name with the new one.
76+
If you were not explicitly using the type names, no changes are needed, since only the class names changed and their behavior remains the same.
77+
78+
List of changed `OneOf` classes and types associated with them:
79+
80+
| Old name | New name |
81+
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
82+
| AiAgentAskOrAiAgentExtractOrAiAgentExtractStructuredOrAiAgentTextGen | AiAgent |
83+
| AiAgentAskOrAiAgentReference | AiAskAgent |
84+
| AiAgentExtractOrAiAgentReference | AiExtractAgent |
85+
| AiAgentExtractStructuredOrAiAgentReference | AiExtractStructuredAgent |
86+
| AiAgentReferenceOrAiAgentTextGen | AiTextGenAgent |
87+
| AppItemEventSourceOrEventSourceOrFileOrFolderOrGenericSourceOrUser | EventSourceResource |
88+
| FileBaseOrFolderBaseOrWebLinkBase | AppItemAssociatedItem |
89+
| FileFullOrFolderFull | MetadataQueryResultItem |
90+
| FileFullOrFolderFullOrWebLink | SearchResultWithSharedLinkItem/RecentItemResource/SearchResultItem |
91+
| FileFullOrFolderMiniOrWebLink | Item |
92+
| FileMiniOrFolderMini | Resource |
93+
| FileOrFolderOrWebLink | LegalHoldPolicyAssignedItem/CollaborationItem |
94+
| FileOrFolderScope | ResourceScope |
95+
| FileOrFolderScopeScopeField | ResourceScopeScopeField |
96+
| FileReferenceOrFolderReferenceOrWeblinkReferenceV2025R0 | HubItemReferenceV2025R0 |
97+
| GroupMiniOrUserCollaborations | CollaborationAccessGrantee |
98+
| IntegrationMappingPartnerItemSlackUnion | IntegrationMappingPartnerItemSlack |
99+
| IntegrationMappingPartnerItemTeamsUnion | IntegrationMappingPartnerItemTeams |
100+
| KeywordSkillCardOrStatusSkillCardOrTimelineSkillCardOrTranscriptSkillCard | SkillCard |
101+
| MetadataFieldFilterDateRangeOrMetadataFieldFilterFloatRangeOrArrayOfStringOrNumberOrString | MetadataFilterValue |
102+
| SearchResultsOrSearchResultsWithSharedLinks | SearchResultsResponse |
103+
104+
Some classes were split into multiple ones depending on context.
105+
106+
Manager functions affected by these changes:
107+
108+
| Function | Old return type | New return type |
109+
| -------------------------------------- | -------------------------------------------------------------------- | --------------------- |
110+
| AiManager.getAiAgentDefaultConfig(...) | AiAgentAskOrAiAgentExtractOrAiAgentExtractStructuredOrAiAgentTextGen | AiAgent |
111+
| SearchManager.searchForContent(...) | SearchResultsOrSearchResultsWithSharedLinks | SearchResultsResponse |
112+
113+
## Removed unused models from schemas namespace
114+
115+
Several unused types (classes and enums) have been removed from the schemas because they were not used by any SDK functions or by the Box API.
116+
117+
### How to migrate
118+
119+
Here is the full list of removed types:
120+
121+
| Removed classes/enums |
122+
| ------------------------------------------ |
123+
| FileOrFolder |
124+
| HubActionV2025R0 |
125+
| MetadataQueryIndex |
126+
| MetadataQueryIndexFieldsField |
127+
| MetadataQueryIndexFieldsSortDirectionField |
128+
| MetadataQueryIndexStatusField |
129+
| RetentionPolicyAssignmentBase |
130+
| RetentionPolicyAssignmentBaseTypeField |
131+
| SkillInvocation |
132+
| SkillInvocationEnterpriseField |
133+
| SkillInvocationEnterpriseTypeField |
134+
| SkillInvocationSkillField |
135+
| SkillInvocationSkillTypeField |
136+
| SkillInvocationStatusField |
137+
| SkillInvocationStatusStateField |
138+
| SkillInvocationTokenField |
139+
| SkillInvocationTokenReadField |
140+
| SkillInvocationTokenReadTokenTypeField |
141+
| SkillInvocationTokenWriteField |
142+
| SkillInvocationTokenWriteTokenTypeField |
143+
| SkillInvocationTypeField |
144+
| WebhookInvocation |
145+
| WebhookInvocationTriggerField |
146+
| WebhookInvocationTypeField |
147+
| WorkflowFull |
148+
149+
If your code references any of these types, remove those references.

0 commit comments

Comments
 (0)