fix: improve openapi instructions for windows/java (#962)

sxlijin · web-flow · commit 6010efbb7990 · 2024-09-16T20:11:41.000-07:00
diff --git a/docs/docs/get-started/quickstart/openapi.mdx b/docs/docs/get-started/quickstart/openapi.mdx
@@ -70,9 +70,18 @@ you can get a client library for free.
         </Tab>
 
         <Tab title="Windows">
-          To install `npx`, use the [Node.js installer](https://nodejs.org/en/download/prebuilt-installer).
+          To install `npx` and `java`:
+
+            1. Use the [Node.js installer](https://nodejs.org/en/download/prebuilt-installer) to install `npx` (default installer settings are fine).
+            2. Run `npm install -g npm@latest` to update `npx` (there is currently an [issue][npx-windows-issue] with the default install of `npx` on Windows where it doesn't work out of the box).
+            3. Run the [Adoptium OpenJDK `.msi` installer](https://adoptium.net/temurin/releases/?os=windows) (install the JDK; default installer settings are fine).
 
-          To install `java`, use the [Adoptium OpenJDK `.msi` installer](https://adoptium.net/temurin/releases/?os=windows).
+          You can verify that `npx` and `java` are installed by running:
+          
+          ```powershell
+          npx -version
+          java -version
+          ```
         </Tab>
 
         <Tab title="Other">
@@ -89,10 +98,17 @@ you can get a client library for free.
       on your needs, we can also provide a static binary for using BAML.
       </Note>
 
-  
+  [npx-windows-issue]: https://github.com/nodejs/node/issues/53538
+
   ### Create a new BAML project
 
-  This will give you some starter BAML code in a `baml_src` directory.
+  This will give you some starter BAML code in a `baml_src` directory, and also
+  set up `generator.baml` based on `--openapi-client-type`, so that BAML will:
+  
+  - compile your BAML functions into an OpenAPI specification, and 
+  - configure `on_generate` to generate an OpenAPI client in the language of your choosing
+
+  <p></p>
 
   <Tabs>
 
@@ -122,10 +138,23 @@ you can get a client library for free.
   </Tab>
 
   <Tab title="Java">
+  
   ```bash
   npx @boundaryml/baml init \
     --client-type rest/openapi --openapi-client-type java
   ```
+
+  Notice that `on_generate` has been initialized for you to:
+
+  - run the OpenAPI generator to generate a Java client library, and _also_
+  - run `mvn clean install` to install the generated client library to your
+    local Maven repository
+
+  <Warning>
+    If you only use Maven through an IDE (e.g. IntelliJ IDEA), you should
+    remove `&& mvn clean install` from the generated `on_generate` command.
+  </Warning>
+
   </Tab>
 
   <Tab title="PHP">
@@ -135,6 +164,13 @@ you can get a client library for free.
   ```
   </Tab>
 
+  <Tab title="Ruby">
+  ```bash
+  npx @boundaryml/baml init \
+    --client-type rest/openapi --openapi-client-type ruby
+  ```
+  </Tab>
+
   <Tab title="Rust">
   ```bash
   npx @boundaryml/baml init \
@@ -225,17 +261,114 @@ func main() {
 </Tab>
 
 <Tab title="Java">
-<Warning>
-  The README that the Java OpenAPI generator generates will have one mistake: it
-  will suggest importing from `baml_client.models.*`, but the correct
-  package to import from is `baml_client.model.*`. The OpenAPI team
-  will [fix this
-  soon](https://github.com/OpenAPITools/openapi-generator/issues/19431).
-</Warning>
+First, add the OpenAPI-generated client to your project.
+
+<AccordionGroup>
+
+<Accordion title="If you have 'mvn' in your PATH">
+
+You can use the default `on_generate` command, which will tell `baml dev` to
+install the OpenAPI-generated client into your local Maven repository by running
+`mvn clean install` every time you save a change to a BAML file.
+
+To depend on the client in your local Maven repo, you can use these configs:
+
+<CodeGroup>
+```xml pom.xml
+<dependency>
+  <groupId>org.openapitools</groupId>
+  <artifactId>openapi-java-client</artifactId>
+  <version>0.1.0</version>
+  <scope>compile</scope>
+</dependency>
+```
+
+```kotlin settings.gradle.kts
+repositories {
+    mavenCentral()
+    mavenLocal()
+}
+
+dependencies {
+    implementation("org.openapitools:openapi-java-client:0.1.0")
+}
+```
+</CodeGroup>
+
+</Accordion>
+
+<Accordion title="If you don't have 'mvn' in your PATH">
+
+You'll probably want to comment out `on_generate` and instead use either the [OpenAPI Maven plugin] or [OpenAPI Gradle plugin] to build your OpenAPI client.
+
+[OpenAPI Maven plugin]: https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin
+[OpenAPI Gradle plugin]: https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-gradle-plugin
+
+<CodeGroup>
+```xml pom.xml
+<build>
+    <plugins>
+        <plugin>
+            <groupId>org.openapitools</groupId>
+            <artifactId>openapi-generator-maven-plugin</artifactId>
+            <version>7.8.0</version> <!-- Use the latest stable version -->
+            <executions>
+                <execution>
+                    <goals>
+                        <goal>generate</goal>
+                    </goals>
+                    <configuration>
+                        <inputSpec>${project.basedir}/baml_client/openapi.yaml</inputSpec>
+                        <generatorName>baml</generatorName> <!-- or another generator name, e.g. 'kotlin' or 'spring' -->
+                        <output>${project.build.directory}/generated-sources/openapi</output>
+                        <apiPackage>com.boundaryml.baml_client.api</apiPackage>
+                        <modelPackage>com.boundaryml.baml_client.model</modelPackage>
+                        <invokerPackage>com.boundaryml.baml_client</invokerPackage>
+                        <java8>true</java8>
+                    </configuration>
+                </execution>
+            </executions>
+        </plugin>
+    </plugins>
+</build>
+```
+
+```kotlin settings.gradle.kts
+plugins {
+    id("org.openapi.generator") version "7.8.0"
+}
+
+openApiGenerate {
+    generatorName.set("java") // Change to 'kotlin', 'spring', etc. if needed
+    inputSpec.set("${projectDir}/baml_client/openapi.yaml")
+    outputDir.set("$buildDir/generated-sources/openapi")
+    apiPackage.set("com.boundaryml.baml_client.api")
+    modelPackage.set("com.boundaryml.baml_client.model")
+    invokerPackage.set("com.boundaryml.baml_client")
+    additionalProperties.set(mapOf("java8" to "true"))
+}
+
+sourceSets["main"].java {
+    srcDir("$buildDir/generated-sources/openapi/src/main/java")
+}
+
+tasks.named("compileJava") {
+    dependsOn("openApiGenerate")
+}
+```
+</CodeGroup>
+
+</Accordion>
+</AccordionGroup>
+
+Then, copy this code into wherever your `main` function is:
+
 ```Java
 import com.boundaryml.baml_client.ApiClient;
 import com.boundaryml.baml_client.ApiException;
 import com.boundaryml.baml_client.Configuration;
+// NOTE: baml_client/README.md will suggest importing from models.* - that is wrong.
+// See https://github.com/OpenAPITools/openapi-generator/issues/19431 for more details.
 import com.boundaryml.baml_client.model.*;
 import com.boundaryml.baml_client.api.DefaultApi;
 
@@ -268,6 +401,8 @@ public class Example {
   you, and you need help working around it.
 </Warning>
 
+First, add the OpenAPI-generated client to your project:
+
 ```json composer.json
     "repositories": [
         {
@@ -280,6 +415,8 @@ public class Example {
     }
 ```
 
+You can now use this code to call a BAML function:
+
 ```PHP
 <?php
 require_once(__DIR__ . '/vendor/autoload.php');
@@ -350,11 +487,15 @@ end
   ```
 </Tip>
 
+First, add the OpenAPI-generated client to your project:
+
 ```toml Cargo.toml
 [dependencies]
 baml-client = { path = "./baml_client" }
 ```
 
+You can now use `cargo run`:
+
 ```rust
 use baml_client::models::ExtractResumeRequest;
 use baml_client::apis::default_api as b;
diff --git a/engine/Cargo.lock b/engine/Cargo.lock
diff --git a/engine/baml-runtime/Cargo.toml b/engine/baml-runtime/Cargo.toml
@@ -123,6 +123,7 @@ reqwest = { version = "0.12.5", features = [
   "stream",
 ] }
 walkdir = "2.5.0"
+which = "6.0.3"
 
 [features]
 defaults = []
diff --git a/engine/baml-runtime/src/cli/init.rs b/engine/baml-runtime/src/cli/init.rs
@@ -3,6 +3,7 @@ use std::{path::PathBuf, process::Command};
 use anyhow::Result;
 use baml_types::GeneratorOutputType;
 use include_dir::include_dir;
+use which::which;
 
 #[derive(clap::Args, Debug)]
 pub struct InitArgs {
@@ -29,23 +30,15 @@ static SAMPLE_PROJECT: include_dir::Dir =
 
 /// TODO: one problem with this impl - this requires all users to install openapi-generator the same way
 fn infer_openapi_command() -> Result<&'static str> {
-    if Command::new("which")
-        .args(["openapi-generator"])
-        .output()
-        .is_ok_and(|output| output.status.success())
-    {
+    if which("openapi-generator").is_ok() {
         return Ok("openapi-generator");
     }
 
-    if Command::new("which")
-        .args(["openapi-generator-cli"])
-        .output()
-        .is_ok_and(|output| output.status.success())
-    {
+    if which("openapi-generator-cli").is_ok() {
         return Ok("openapi-generator-cli");
     }
 
-    if Command::new("npx").args(["--version"]).status().is_ok() {
+    if which("npx").is_ok() {
         return Ok("npx @openapitools/openapi-generator-cli");
     }
 
@@ -74,7 +67,10 @@ impl InitArgs {
         let openapi_generator_path = infer_openapi_command();
 
         if let Err(e) = &openapi_generator_path {
-            log::warn!("OpenAPI client generator will be skipped, since we failed to find one in your PATH: {}", e);
+            log::warn!(
+                "Failed to find openapi-generator-cli in your PATH, defaulting to using npx: {}",
+                e
+            );
         }
 
         let main_baml_content = generate_main_baml_content(
@@ -140,7 +136,7 @@ fn generate_main_baml_content(
             "{cmd} --additional-properties enumClassPrefix=true,isGoSubmodule=true,packageName=baml_client,withGoMod=false",
         ),
         Some("java") => format!(
-            "{cmd} --additional-properties invokerPackage=com.boundaryml.baml_client,modelPackage=com.boundaryml.baml_client.model,apiPackage=com.boundaryml.baml_client.api,java8=true && cd ../baml_client && mvn clean install",
+            "{cmd} --additional-properties invokerPackage=com.boundaryml.baml_client,modelPackage=com.boundaryml.baml_client.model,apiPackage=com.boundaryml.baml_client.api,java8=true && mvn clean install",
         ),
         Some("php") => format!(
             "{cmd} --additional-properties composerPackageName=boundaryml/baml-client,invokerPackage=BamlClient",
@@ -349,7 +345,7 @@ generator target {{
 
     // 'baml-cli generate' will run this after generating openapi.yaml, to generate your OpenAPI client
     // This command will be run from within $output_dir
-    on_generate "openapi-generator generate -i openapi.yaml -g java -o . --additional-properties invokerPackage=com.boundaryml.baml_client,modelPackage=com.boundaryml.baml_client.model,apiPackage=com.boundaryml.baml_client.api,java8=true && cd ../baml_client && mvn clean install"
+    on_generate "openapi-generator generate -i openapi.yaml -g java -o . --additional-properties invokerPackage=com.boundaryml.baml_client,modelPackage=com.boundaryml.baml_client.model,apiPackage=com.boundaryml.baml_client.api,java8=true && mvn clean install"
 }}
 "#,
                 env!("CARGO_PKG_VERSION")
