From 87924073f9bfac0dd6202f724dcfe0ac7125b3f8 Mon Sep 17 00:00:00 2001 From: Vishal Gowda Date: Wed, 11 Jun 2025 08:38:44 +0100 Subject: [PATCH 1/2] Add Java support to custom code regions documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Updated overview page to include Java in supported languages list - Created comprehensive Java documentation with configuration, regions, and examples - Added dependency management section for external packages - Included complete code example with CommonMark integration 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- docs/customize/code/code-regions/java.mdx | 103 ++++++++++++++++++ docs/customize/code/code-regions/overview.mdx | 1 + 2 files changed, 104 insertions(+) create mode 100644 docs/customize/code/code-regions/java.mdx diff --git a/docs/customize/code/code-regions/java.mdx b/docs/customize/code/code-regions/java.mdx new file mode 100644 index 00000000..1cb4f703 --- /dev/null +++ b/docs/customize/code/code-regions/java.mdx @@ -0,0 +1,103 @@ +--- +title: Custom code regions in Java +description: "Learn how to use custom code regions in Java SDKs." +--- + +# Custom code regions in Java + +To enable custom code regions for Java SDKs, update the project's +`.speakeasy/gen.yaml` file like so: + +```diff .speakeasy/gen.yaml +configVersion: 2.0.0 +generation: + # ... +java: + # ... ++ enableCustomCodeRegions: true +``` + +## Full example + +The Speakeasy examples repository has a [full example](https://github.com/speakeasy-api/examples/tree/main/customcode-sdkclasses-java) of a Java SDK +that uses custom code regions. + + +## Regions + +Below are the available code regions in Java SDKs. + +### SDK classes + +Java SDK classes can have two code regions: + +* `// #region imports` - allows the addition of imports to an SDK file needed for +custom methods and properties. This region must be located at the top of the +file alongside generated imports. +* `// #region sdk-class-body` - allows the addition of custom methods and +properties to an SDK class. This region must be located in the body of a Java +SDK class alongside generated methods and properties. + +## Managing dependencies + +When adding custom code that requires external packages, configure these dependencies in the `.speakeasy/gen.yaml` file to prevent them from being removed during SDK regeneration. Use the `additionalDependencies` configuration to specify package dependencies: + +```yaml .speakeasy/gen.yaml +java: + additionalDependencies: + compile: + - "org.commonmark:commonmark:0.21.0" + - "org.jsoup:jsoup:1.16.1" + testCompile: + - "org.junit.jupiter:junit-jupiter:5.9.2" + - "org.mockito:mockito-core:5.1.1" +``` + +This ensures dependencies persist across SDK regenerations and are properly included in the generated `build.gradle`. + +```java src/main/java/com/example/sdk/Todos.java +/* + * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT. + */ + +package com.example.sdk; + +import com.example.sdk.models.operations.*; +import com.example.sdk.models.shared.*; +import com.example.sdk.utils.HTTPClient; +import com.example.sdk.utils.HTTPRequest; +import com.example.sdk.utils.Utils; + +// !focus(1:3) +// #region imports +import org.commonmark.parser.Parser; +import org.commonmark.renderer.html.HtmlRenderer; +// #endregion imports + +public class Todos { + private HTTPClient _client; + + public Todos(HTTPClient client) { + this._client = client; + } + + // !focus(1:11) + // #region sdk-class-body + public String renderTodo(String id) throws Exception { + Todo todo = getOne(id); + + Parser parser = Parser.builder().build(); + HtmlRenderer renderer = HtmlRenderer.builder().build(); + + String markdown = String.format("# %s\n\n%s", todo.title, todo.description); + + return renderer.render(parser.parse(markdown)); + } + // #endregion sdk-class-body + + public Todo getOne(String id) throws Exception { + // Generated method implementation + ... + } +} +``` \ No newline at end of file diff --git a/docs/customize/code/code-regions/overview.mdx b/docs/customize/code/code-regions/overview.mdx index 12c89c51..348a90bb 100644 --- a/docs/customize/code/code-regions/overview.mdx +++ b/docs/customize/code/code-regions/overview.mdx @@ -36,5 +36,6 @@ for [creating code folds](https://code.visualstudio.com/docs/editor/codebasics#_ Custom code regions are currently supported in the following languages: +- [Java](/docs/customize/code/code-regions/java) - [Python](/docs/customize/code/code-regions/python) - [TypeScript](/docs/customize/code/code-regions/typescript) From 7f1a9f2eae6a755f6d44a55da8e0a252d0dcfb71 Mon Sep 17 00:00:00 2001 From: Vishal Gowda Date: Wed, 11 Jun 2025 09:19:16 +0100 Subject: [PATCH 2/2] chore: wip --- docs/customize/code/code-regions/java.mdx | 36 ++++++++++++----------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/docs/customize/code/code-regions/java.mdx b/docs/customize/code/code-regions/java.mdx index 1cb4f703..befcf6fe 100644 --- a/docs/customize/code/code-regions/java.mdx +++ b/docs/customize/code/code-regions/java.mdx @@ -45,12 +45,10 @@ When adding custom code that requires external packages, configure these depende ```yaml .speakeasy/gen.yaml java: additionalDependencies: - compile: - - "org.commonmark:commonmark:0.21.0" - - "org.jsoup:jsoup:1.16.1" - testCompile: - - "org.junit.jupiter:junit-jupiter:5.9.2" - - "org.mockito:mockito-core:5.1.1" + - implementation:org.commonmark:commonmark:0.21.0 + - implementation:org.jsoup:jsoup:1.16.1 + - testImplementation:org.junit.jupiter:junit-jupiter:5.9.2 + - testImplementation:org.mockito:mockito-core:5.1.1 ``` This ensures dependencies persist across SDK regenerations and are properly included in the generated `build.gradle`. @@ -74,23 +72,27 @@ import org.commonmark.parser.Parser; import org.commonmark.renderer.html.HtmlRenderer; // #endregion imports -public class Todos { - private HTTPClient _client; - - public Todos(HTTPClient client) { - this._client = client; +public class Todos implements + MethodCallCreate, + MethodCallGetOne { + + private final SDKConfiguration sdkConfiguration; + + Todos(SDKConfiguration sdkConfiguration) { + this.sdkConfiguration = sdkConfiguration; } - + // !focus(1:11) // #region sdk-class-body public String renderTodo(String id) throws Exception { - Todo todo = getOne(id); - + Todo todo = getOne(id).todo() + .orElseThrow(() -> new Exception("Todo not found")); + Parser parser = Parser.builder().build(); HtmlRenderer renderer = HtmlRenderer.builder().build(); - - String markdown = String.format("# %s\n\n%s", todo.title, todo.description); - + + String markdown = String.format("# %s\n\n%s", todo.title(), todo.description()); + return renderer.render(parser.parse(markdown)); } // #endregion sdk-class-body