CSAP Framework API Doc - Quick Start Guide¶
This guide will help you integrate CSAP Framework API Doc into your Spring Boot project in just 5 minutes.
📋 Prerequisites¶
Before you begin, ensure you have: - ✅ JDK 8 or higher installed (Recommended: JDK 8 or JDK 11) - ✅ Maven 3.6+ or Gradle 6+ - ✅ An existing Spring Boot 2.x project
🚀 Step 1: Add Dependency¶
Maven¶
Add the following dependency to your pom.xml:
<dependency>
<groupId>ai.csap.apidoc.boot</groupId>
<artifactId>csap-apidoc-boot-starter</artifactId>
<version>1.1.0</version>
</dependency>
Gradle¶
Add the following to your build.gradle:
⚙️ Step 2: Enable API Documentation (Annotation-Based - Recommended)¶
Add @EnableApidoc annotation to your Spring Boot Application class:
package com.yourcompany.yourproject;
import ai.csap.apidoc.boot.autoconfigure.EnableApidoc;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
@EnableApidoc("com.yourcompany.yourproject") // Specify package to scan
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
Parameter Strategy Types¶
CSAP Apidoc supports multiple strategies for managing API parameters. Configure via paramType:
1. ANNOTATION Strategy (Default - Recommended)
@EnableApidoc(
value = "com.yourcompany.yourproject",
paramType = ApiStrategyType.ANNOTATION // Use annotations to define parameters
)
@ApiProperty, @ApiModelProperty annotations
- Most flexible and easy to maintain
- This is the default and recommended approach
2. SQLite Strategy
@EnableApidoc(
value = "com.yourcompany.yourproject",
paramType = ApiStrategyType.SQL_LITE, // Store parameter configs in SQLite
path = "csap-example", // Storage path
fileName = "example-db" // SQLite database file name
)
Using Environment Variables (Recommended for path and fileName):
@EnableApidoc(
value = "com.yourcompany.yourproject",
paramType = ApiStrategyType.SQL_LITE,
path = "${csap.apidoc.path:csap-example}", // Use env variable with default
fileName = "${csap.apidoc.filename:example-db}" // Use env variable with default
)
Then configure in application.yml:
Or use system environment variables:
3. YAML Strategy
@EnableApidoc(
value = "com.yourcompany.yourproject",
paramType = ApiStrategyType.YAML, // Store parameter configs in YAML files
path = "csap-docs" // YAML file storage path
)
4. Advanced Configuration with Multiple Packages
@EnableApidoc(
apiPackages = {"com.yourcompany.yourproject.controller"}, // API controller packages
enumPackages = {"com.yourcompany.yourproject.enums"}, // Enum packages
modelPackages = {"com.yourcompany.yourproject.model"}, // Model packages
paramType = ApiStrategyType.ANNOTATION, // Strategy type
showChildPackageFlag = true // Scan child packages
)
Optional: YAML Configuration (For DevTools)¶
If you want to enable DevTools, add to application.yml:
📝 Step 3: Annotate Your Controllers¶
Add documentation annotations to your REST controllers:
Simple Example¶
package com.yourcompany.yourproject.controller;
import ai.csap.apidoc.annotation.*;
import org.springframework.web.bind.annotation.*;
import jakarta.validation.Valid;
@RestController
@RequestMapping("/api/users")
@Api(tags = "User Management", description = "User related operations")
public class UserController {
@GetMapping("/{id}")
@ApiOperation(value = "Get User by ID", description = "Retrieve user information by user ID")
public User getUser(@PathVariable Long id) {
// Your business logic
return userService.getById(id);
}
@PostMapping
@ApiOperation(value = "Create User", description = "Create a new user account")
public User createUser(@Valid @RequestBody User user) {
// Your business logic
return userService.create(user);
}
}
Document Your Models¶
package com.yourcompany.yourproject.model;
import ai.csap.apidoc.annotation.apidoc.ApiModel;
import ai.csap.apidoc.annotation.apidoc.ApiModelProperty;
@ApiModel(description = "User entity")
public class User {
@ApiModelProperty(value = "User ID", example = "1001")
private Long id;
@ApiModelProperty(value = "Username", required = true, example = "john_doe")
private String username;
@ApiModelProperty(value = "Email address", example = "john@example.com")
private String email;
@ApiModelProperty(value = "User status", example = "ACTIVE")
private String status;
// Getters and setters...
}
🎯 Step 4: Run and Access¶
-
Start your Spring Boot application:
-
Look for the startup banner in your console:
-
Access the documentation in your browser:
- UI Interface:
http://localhost:8080/csap-api.html - JSON API:
http://localhost:8080/api/csap/doc
🎨 Step 5: Explore Features¶
Online Testing¶
- Navigate to any API endpoint in the UI
- Click the "Test" button
- Fill in parameters
- Click "Send Request"
- View the response
Export Documentation¶
- Postman: Export collection and import into Postman
- Markdown: Generate readable documentation
- OpenAPI/Swagger: Export in standard format
Configure Fields¶
- Click on any API endpoint
- Use the "Field Management" section
- Add optional fields from the field library
- Configure validation rules
🔧 Advanced Configuration¶
Enable DevTools (Optional)¶
DevTools provides a visual interface for managing API documentation:
Choosing the Right Strategy¶
| Strategy | Use Case | Pros | Cons |
|---|---|---|---|
| ANNOTATION (Default) | Standard API documentation | Type-safe, IDE support, easy maintenance | Requires code annotations |
| SQL_LITE | Dynamic parameter management | Visual configuration, no code changes needed | Requires database file |
| YAML | Version-controlled documentation | Human-readable, easy to review | Manual file editing |
Strategy Comparison Example:
// Option 1: Pure Annotation (Default - Recommended)
@EnableApidoc("com.yourcompany.yourproject")
// Option 2: SQLite for dynamic configuration
@EnableApidoc(
value = "com.yourcompany.yourproject",
paramType = ApiStrategyType.SQL_LITE,
path = "csap-example",
fileName = "example-db"
)
// Option 3: YAML for version control
@EnableApidoc(
value = "com.yourcompany.yourproject",
paramType = ApiStrategyType.YAML,
path = "api-docs"
)
// Option 4: Using environment variables (Best Practice)
@EnableApidoc(
value = "com.yourcompany.yourproject",
paramType = ApiStrategyType.SQL_LITE,
path = "${csap.apidoc.path:csap-default}",
fileName = "${csap.apidoc.file:apidoc}"
)
Environment Variable Support¶
path and fileName support Spring Boot placeholder syntax:
Syntax:
- ${property.name} - Use property value, error if not found
- ${property.name:defaultValue} - Use property value or default
Example:
@EnableApidoc(
value = "com.yourcompany.yourproject",
paramType = ApiStrategyType.SQL_LITE,
path = "${apidoc.data.path:/tmp/apidoc}", // Use /tmp/apidoc if not configured
fileName = "${apidoc.db.file:${spring.application.name}}" // Use app name as default
)
Configure in application.yml or application.properties:
Or use system environment variables:
Benefits: - ✅ Different configs for dev/test/prod environments - ✅ Centralized configuration management - ✅ Easy to override via environment variables - ✅ Supports Docker and Kubernetes deployments
Disable in Production¶
Option 1: Using Spring Profiles (Recommended)
@SpringBootApplication
@EnableApidoc(value = "com.yourcompany.yourproject")
public class Application {
// Only enable apidoc in dev/test profiles
}
Then in application-prod.yml:
API Gateway Aggregation (Microservices)¶
For microservice architecture or API gateway scenarios, you can aggregate multiple service documentations in one place:
Use Case: You have multiple microservices (Admin API, Store API, Other API) behind a gateway, and you want to view all their documentation from a single interface.
Configuration in Gateway Project:
# application.yml in your API Gateway project
csap:
apidoc:
resources:
- name: Admin API
url: /example-admin-api/csap/apidoc/parent
version: v1.0
- name: Store API
url: /example-store-api/csap/apidoc/parent
version: v1.0
- name: Other API
url: /example-other-api/csap/apidoc/parent
version: v1.0
How It Works:
- Each microservice exposes its own API documentation endpoint
- Gateway aggregates all service endpoints in the
resourcesconfiguration - Frontend UI provides a dropdown to switch between services
- Users can view all service documentation from a single entry point
Benefits:
- ✅ Unified documentation portal for all microservices
- ✅ No need to remember different service URLs
- ✅ Quick switching between service documentation
- ✅ Perfect for Spring Cloud Gateway, Kong, APISIX, Nginx
📚 Complete Example¶
Here's a complete, working example:
Project Structure¶
src/
├── main/
│ ├── java/
│ │ └── com/example/demo/
│ │ ├── DemoApplication.java
│ │ ├── controller/
│ │ │ └── UserController.java
│ │ ├── model/
│ │ │ └── User.java
│ │ └── service/
│ │ └── UserService.java
│ └── resources/
│ └── application.yml
DemoApplication.java¶
package com.example.demo;
import ai.csap.apidoc.boot.autoconfigure.EnableApidoc;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
@EnableApidoc(
apiPackages = {"com.example.demo.controller"},
modelPackages = {"com.example.demo.model"}
)
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
application.yml (Optional - for DevTools)¶
server:
port: 8080
spring:
application:
name: demo-api
csap:
apidoc:
devtool:
enabled: true # Enable DevTools UI
UserController.java¶
package com.example.demo.controller;
import ai.csap.apidoc.annotation.*;
import com.example.demo.model.User;
import com.example.demo.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/api/users")
@Api(tags = "User Management", description = "User CRUD operations")
public class UserController {
@Autowired
private UserService userService;
@GetMapping
@ApiOperation(value = "List All Users", description = "Get all users in the system")
public List<User> listUsers() {
return userService.findAll();
}
@GetMapping("/{id}")
@ApiOperation(value = "Get User", description = "Get user by ID")
public User getUser(
@ApiProperty(value = "User ID", required = true, example = "1")
@PathVariable Long id) {
return userService.findById(id);
}
@PostMapping
@ApiOperation(value = "Create User", description = "Create a new user")
public User createUser(
@ApiModel(description = "User data")
@RequestBody User user) {
return userService.create(user);
}
@PutMapping("/{id}")
@ApiOperation(value = "Update User", description = "Update existing user")
public User updateUser(
@ApiProperty(value = "User ID", required = true)
@PathVariable Long id,
@ApiModel(description = "Updated user data")
@RequestBody User user) {
return userService.update(id, user);
}
@DeleteMapping("/{id}")
@ApiOperation(value = "Delete User", description = "Delete user by ID")
public void deleteUser(
@ApiProperty(value = "User ID", required = true)
@PathVariable Long id) {
userService.delete(id);
}
}
User.java¶
package com.example.demo.model;
import ai.csap.apidoc.annotation.apidoc.ApiModel;
import ai.csap.apidoc.annotation.apidoc.ApiModelProperty;
import jakarta.validation.constraints.*;
@ApiModel(description = "User entity")
public class User {
@ApiModelProperty(value = "User ID", example = "1")
private Long id;
@ApiModelProperty(value = "Username", required = true, example = "john_doe")
@NotBlank(message = "Username cannot be blank")
@Size(min = 3, max = 50)
private String username;
@ApiModelProperty(value = "Email", required = true, example = "john@example.com")
@Email(message = "Invalid email format")
@NotBlank(message = "Email cannot be blank")
private String email;
@ApiModelProperty(value = "Age", example = "25")
@Min(value = 18, message = "Age must be at least 18")
@Max(value = 120, message = "Age must be less than 120")
private Integer age;
@ApiModelProperty(value = "Phone number", example = "13800138000")
@Pattern(regexp = "^1[3-9]\\d{9}$", message = "Invalid phone number")
private String phone;
@ApiModelProperty(value = "Account status", example = "ACTIVE")
private String status;
// Getters and setters
// ...
}
🎉 That's It!¶
You now have a fully functional API documentation system!
🆘 Troubleshooting¶
Documentation not showing?¶
- Check that
enabled: truein configuration - Verify
base-packagematches your package structure - Check application logs for errors
Can't access the UI?¶
- Verify the URL (check for context path)
- Check if port 8080 is accessible
- Look for startup banner with the correct URL
APIs not appearing?¶
- Ensure controllers have
@RestControlleror@Controller - Verify controllers are in the scanned package
- Add
@Apiannotation to controllers
📖 Next Steps¶
- 📚 Read the Full Documentation
- 🔧 Explore Advanced Configuration
- 🎨 Customize the DevTools Interface
- 🚀 Check out the Product Roadmap
- 💬 Join our Community Discussions
🤝 Need Help?¶
- 📧 Email: support@csap.com
- 🐛 Report Issues: GitHub Issues
- 💬 Ask Questions: GitHub Discussions
Happy documenting! 🎊