# OpenAPI Generation Instructions
## Overview
The OpenAPI package in `pkg/openapi` provides functionality to generate server code from OpenAPI specifications. This document explains how to use this package to generate and host multiple APIs under a single server with Swagger UI integration.
## Implementation Status
We have successfully implemented:
1. A proper test in `pkg/openapi/examples` that generates code from OpenAPI specifications
2. Code generation for two example APIs:
- `petstoreapi` (from `petstore.yaml`)
- `actionsapi` (from `actions.yaml`)
3. A webserver that hosts multiple generated APIs
4. Swagger UI integration for API documentation
5. A home page with links to the APIs and their documentation
All APIs are hosted under `$serverurl:$port/api` with a clean navigation structure.
## Directory Structure
```
pkg/openapi/
├── examples/
│ ├── actions.yaml # OpenAPI spec for Actions API
│ ├── actionsapi/ # Generated code for Actions API
│ ├── main.go # Main server implementation
│ ├── petstore.yaml # OpenAPI spec for Petstore API
│ ├── petstoreapi/ # Generated code for Petstore API
│ ├── README.md # Documentation for examples
│ ├── run_test.sh # Script to run tests and server
│ └── test/ # Tests for OpenAPI generation
├── generator.go # Server code generator
├── parser.go # OpenAPI spec parser
├── example.go # Example usage
└── templates/ # Code generation templates
└── server.tmpl # Server template
```
## How to Use
### Running the Example
To run the example implementation:
1. Navigate to the examples directory:
```bash
cd pkg/openapi/examples
```
2. Run the test script:
```bash
./run_test.sh
```
3. Access the APIs:
- API Home: http://localhost:9091/api
- Petstore API: http://localhost:9091/api/petstore
- Petstore API Documentation: http://localhost:9091/api/swagger/petstore
- Actions API: http://localhost:9091/api/actions
- Actions API Documentation: http://localhost:9091/api/swagger/actions
### Generating Code from Your Own OpenAPI Spec
To generate code from your own OpenAPI specification:
```go
package main
import (
"fmt"
"os"
"path/filepath"
"github.com/freeflowuniverse/heroagent/pkg/openapi"
)
func main() {
// Parse the OpenAPI specification
spec, err := openapi.ParseFromFile("your-api.yaml")
if err != nil {
fmt.Printf("Failed to parse OpenAPI specification: %v\n", err)
os.Exit(1)
}
// Create a server generator
generator := openapi.NewServerGenerator(spec)
// Generate server code
serverCode := generator.GenerateServerCode()
// Write the server code to a file
outputPath := "generated-server.go"
err = os.WriteFile(outputPath, []byte(serverCode), 0644)
if err != nil {
fmt.Printf("Failed to write server code: %v\n", err)
os.Exit(1)
}
fmt.Printf("Generated server code in %s\n", outputPath)
}
```
### Hosting Multiple APIs
To host multiple APIs under a single server:
```go
package main
import (
"fmt"
"github.com/freeflowuniverse/heroagent/pkg/openapi"
"github.com/gofiber/fiber/v2"
)
func main() {
// Create the main server
app := fiber.New()
// Setup API routes
app.Get("/api", func(c *fiber.Ctx) error {
return c.SendString("API Home Page")
})
// Mount the first API
spec1, _ := openapi.ParseFromFile("api1.yaml")
generator1 := openapi.NewServerGenerator(spec1)
apiServer1 := generator1.GenerateServer()
app.Mount("/api/api1", apiServer1)
// Mount the second API
spec2, _ := openapi.ParseFromFile("api2.yaml")
generator2 := openapi.NewServerGenerator(spec2)
apiServer2 := generator2.GenerateServer()
app.Mount("/api/api2", apiServer2)
// Start the server
app.Listen(":8080")
}
```
### Adding Swagger UI
To add Swagger UI for API documentation:
```go
// Serve OpenAPI specs
app.Static("/api/api1/openapi.yaml", "api1.yaml")
app.Static("/api/api2/openapi.yaml", "api2.yaml")
// API1 Swagger UI
app.Get("/api/swagger/api1", func(c *fiber.Ctx) error {
return c.SendString(`
API1 - Swagger UI
`)
})
```
## Features
### OpenAPI Parsing
The package can parse OpenAPI 3.0 and 3.1 specifications from files or byte slices.
### Code Generation
The package generates Fiber server code with mock implementations based on examples in the OpenAPI spec.
### Mock Implementations
Mock implementations are created using examples from the OpenAPI spec, making it easy to test APIs without writing any code.
### Multiple API Hosting
The package supports hosting multiple APIs under a single server, with each API mounted at a different path.
### Swagger UI Integration
The package includes Swagger UI integration for API documentation, making it easy to explore and test APIs.
## Best Practices
1. **Organize Your Code**: Keep your OpenAPI specs, generated code, and server implementation in separate directories.
2. **Use Examples**: Include examples in your OpenAPI spec to generate better mock implementations.
3. **Test Your APIs**: Write tests to verify that your APIs work as expected.
4. **Document Your APIs**: Use Swagger UI to document your APIs and make them easier to use.
5. **Use Version Control**: Keep your OpenAPI specs and generated code in version control to track changes.
## Troubleshooting
- **Parse Error**: If you get a parse error, check that your OpenAPI spec is valid. You can use tools like [Swagger Editor](https://editor.swagger.io/) to validate your spec.
- **Generation Error**: If code generation fails, check that your OpenAPI spec includes all required fields and that examples are properly formatted.
- **Server Error**: If the server fails to start, check that the port is not already in use and that all required dependencies are installed.