openapi-generator-original/samples/server/petstore/java-dubbo/README.md

OpenAPI Petstore

This is a sample server Petstore server. For this sample, you can use the api key `special-key` to test the authorization filters.

This is a microservice project based on Apache Dubbo, generated by OpenAPI Generator.

• API version: 1.0.0
• Package version:
• Generator: org.openapitools.codegen.languages.JavaDubboServerCodegen

Technology Stack

• Framework: Apache Dubbo 3.2.18
• Java: 8+
• Build Tool: Maven 3.6+
• Registry: zookeeper://127.0.0.1:2181
• Serialization: Jackson JSON

System Requirements

Building and running this project requires:

1. Java 8+
2. Maven 3.6+
3. Registry Center (Nacos or Zookeeper)

Quick Start

1. Clone and Build Project

git clone <your-repo-url>
cd openapi-dubbo-server-petstore
mvn clean compile

2. Configure Registry Center

Using Nacos (Recommended)

# Download and start Nacos
wget https://github.com/alibaba/nacos/releases/download/2.2.4/nacos-server-2.2.4.tar.gz
tar -xzf nacos-server-2.2.4.tar.gz
cd nacos/bin
# Linux/Mac
./startup.sh -m standalone
# Windows
startup.cmd -m standalone

Using Zookeeper (Alternative)

# Download and start Zookeeper
wget https://downloads.apache.org/zookeeper/zookeeper-3.8.2/apache-zookeeper-3.8.2-bin.tar.gz
tar -xzf apache-zookeeper-3.8.2-bin.tar.gz
cd apache-zookeeper-3.8.2-bin
cp conf/zoo_sample.cfg conf/zoo.cfg
bin/zkServer.sh start

3. Configure Application

Edit the src/main/resources/application.yml file:

# Dubbo Configuration
dubbo:
  application:
    name: openapi-dubbo-server-petstore
  registry:
    # Using Nacos
    address: nacos://127.0.0.1:8848
    # Or using Zookeeper
    # address: zookeeper://127.0.0.1:2181
  protocol:
    name: dubbo
    port: 20880
  provider:
    timeout: 10000

4. Start Application

# Build project
mvn clean compile

# Run main class
mvn exec:java -Dexec.mainClass=".Application"

Project Structure

openapi-dubbo-server-petstore/
├── src/main/java//
│   └── Application.java                    # Main Application Class
├── src/main/resources/
│   └── application.yml                     # Application Configuration
├── pom.xml                                 # Maven Configuration
└── README.md                               # Project Documentation

API Interfaces

Service Interfaces

Development Guide

Implement Business Logic

1. Implement specific business logic in the generated *DubboImpl.java classes
2. Inject necessary business service dependencies
3. Handle exceptions and error scenarios

Custom Configuration

1. Timeout Configuration: Adjust dubbo.provider.timeout in application.yml
2. Thread Pool Configuration: Configure dubbo.provider.threads and other parameters
3. Serialization Configuration: Choose appropriate serialization method

Monitoring and Operations

1. Health Checks: Dubbo provides built-in health check endpoints
2. Metrics Monitoring: Integrate with Prometheus or other monitoring systems
3. Log Management: Configure appropriate log levels and output formats

Testing

# Run unit tests
mvn test

# Run integration tests
mvn integration-test

Deployment

Development Environment

mvn spring-boot:run

Production Environment

# Build production package
mvn clean package -Pprod

# Deploy using Docker
docker build -t openapi-dubbo-server-petstore:1.0.0 .
docker run -p 8080:8080 -p 20880:20880 openapi-dubbo-server-petstore:1.0.0

Generator Configuration Options

This project supports the following OpenAPI Generator configuration options:

Basic Configuration

• title: API service title name (Default: "OpenAPI Dubbo")
• basePackage: Base package name (Default: "org.openapitools")
• configPackage: Configuration class package name (Default: "org.openapitools.configuration")
• dubboVersion: Dubbo version (Default: "3.2.0")

Generation Control

• interfaceOnly: Generate interfaces only, no implementation classes (Default: false)
• serviceInterface: Generate service interfaces (Default: true)
• serviceImplementation: Generate service implementations (Default: true)
• async: Use asynchronous methods (Default: false)
• useTags: Use tags to create class names (Default: true)
• useGenericResponse: Use generic response wrapper (Default: false)

Registry Configuration

• registry-address: Registry address, supports full address format (Default: "zookeeper://127.0.0.1:2181")
  • Zookeeper example: zookeeper://127.0.0.1:2181
  • Nacos example: nacos://127.0.0.1:8848

📋 Automatic Dependency Adaptation by Version

The generator automatically selects the correct dependencies based on Dubbo version:

Dubbo 3.2 and earlier versions:

• Zookeeper: dubbo-dependencies-zookeeper (Aggregation POM)
• Nacos: dubbo-registry-nacos + nacos-client:2.2.4

Dubbo 3.3+ versions:

• Zookeeper: dubbo-registry-zookeeper + dubbo-remoting-zookeeper-curator5
• Nacos: dubbo-registry-nacos + nacos-client:2.5.0

Date-Time Library Configuration

• dateLibrary: Date-time library selection (Default: "java8")
  • java8: Java 8 native JSR310 (Recommended, for JDK 1.8+)
  • java8-localdatetime: Java 8 using LocalDateTime (For legacy applications only)
  • joda: Joda time library (For legacy applications only)
  • legacy: Traditional java.util.Date

Usage Examples

🔧 Dubbo 3.2 Version Example

# Using Zookeeper (3.2 version automatically uses dubbo-dependencies-zookeeper)
java -jar openapi-generator-cli.jar generate \
-i /Users/redoom/IdeaProjects/openapi.yaml \
-g java-dubbo \
-o /Users/redoom/IdeaProjects/openapi-test \
--additional-properties=registry-address=zookeeper://127.0.0.1:2181 \
--additional-properties=dubboVersion=3.2.0 \
--additional-properties=dateLibrary=java8

# Using Nacos (3.2 version uses nacos-client:2.2.4)
java -jar openapi-generator-cli.jar generate \
-i /Users/redoom/IdeaProjects/openapi.yaml \
-g java-dubbo \
-o /Users/redoom/IdeaProjects/openapi-test \
--additional-properties=registry-address=nacos://127.0.0.1:8848 \
--additional-properties=dubboVersion=3.2.0 \
--additional-properties=dateLibrary=java8

🚀 Dubbo 3.3+ Version Example

# Using Zookeeper (3.3+ version automatically uses new modular dependencies)
java -jar openapi-generator-cli.jar generate \
-i /Users/redoom/IdeaProjects/openapi.yaml \
-g java-dubbo \
-o /Users/redoom/IdeaProjects/openapi-test \
--additional-properties=registry-address=zookeeper://127.0.0.1:2181 \
--additional-properties=dubboVersion=3.3.0 \
--additional-properties=dateLibrary=java8

# Using Nacos (3.3+ version uses nacos-client:2.5.0)
java -jar openapi-generator-cli.jar generate \
-i /Users/redoom/IdeaProjects/openapi.yaml \
-g java-dubbo \
-o /Users/redoom/IdeaProjects/openapi-test \
--additional-properties=registry-address=nacos://127.0.0.1:8848 \
--additional-properties=dubboVersion=3.3.0 \
--additional-properties=dateLibrary=java8

Troubleshooting

Common Issues

1. Registry Connection Failed

   • Check if the registry center is started
   • Verify network connection and port configuration

2. Service Call Timeout

   • Adjust dubbo.provider.timeout settings
   • Check network latency and service performance

3. Serialization Exception

   • Ensure all model classes implement Serializable interface
   • Check Jackson configuration

Debug Logging

Enable debug mode to see detailed logs:

logging:
  level:
    org.apache.dubbo: DEBUG
    : DEBUG

License

This project is licensed under the Apache License 2.0.

Contributing

Issues and Pull Requests are welcome!

Contact

---

This project is automatically generated by OpenAPI Generator, based on Apache Dubbo microservice architecture.