hwiesung/spring-ai-zhipuai

Overview

This skill automates configuring ZhipuAI and Swagger for Kotlin-based Spring AI projects and helps run build and test workflows. It provides concrete Gradle, application.yml, and Swagger annotation changes to get a project running with ZhipuAI models and SpringDoc OpenAPI.

How this skill works

It updates the Gradle wrapper and build settings to JDK 21 and adds the Spring AI ZhipuAI starter and SpringDoc OpenAPI dependencies. It also shows how to set ZhipuAI options in application.yml, add Swagger annotations and example data to models and controllers, then build, test, and run the application. The skill includes verification steps for Swagger UI and API docs and common troubleshooting tips.

When to use it

• Migrating a Kotlin Spring Boot AI project from another model provider to ZhipuAI
• Setting up Swagger (OpenAPI) with example-filled API docs for AI endpoints
• Preparing a project to run on JDK 21 and Gradle 8.12+
• Automating local verification and manual testing via Swagger UI
• Ensuring compatibility with Spring Boot 3.3.x and SpringDoc versions

Best practices

• Run gradle wrapper --gradle-version=8.12 first to avoid build failures
• Use JDK 21 toolchain and set Kotlin jvmTarget to 21 for consistency
• Store the ZhipuAI API key in an environment variable (ZHIPUAI_API_KEY)
• Annotate models with @Schema examples so Swagger auto-fills realistic request data
• Pin SpringDoc to a compatible starter version to avoid runtime class issues

Example use cases

• Replace an existing OpenAI/Ollama dependency with org.springframework.ai:spring-ai-starter-model-zhipuai to call ZhipuAI models
• Add @Operation and @Tag annotations to controllers so Swagger UI shows descriptions and example requests
• Configure application.yml to select a ZhipuAI model (e.g., glm-4.7-flash) and adjust temperature
• Run ./gradlew clean build -x test and ./gradlew test to validate build and unit tests
• Use Swagger UI at /swagger-ui.html to try endpoints and confirm example payloads execute correctly