openapi-go

To generate a full OpenAPI specification, follow these steps:

1. Initialize an openapi3.Reflector.
2. Configure the Spec (e.g., set Openapi version, Info.Title, Info.Version).
3. Create operations using reflector.NewOperationContext(method, path).
4. Attach request and response structures to the operation using AddReqStructure and AddRespStructure.
5. Register the operation with reflector.AddOperation(op).
6. Marshal the resulting spec to YAML or JSON.

reflector := openapi3.Reflector{}
reflector.Spec = &openapi3.Spec{Openapi: "3.0.3"}
reflector.Spec.Info.WithTitle("API").WithVersion("1.0.0")

// Define an operation
op, _ := reflector.NewOperationContext(http.MethodGet, "/items/{id}")
type Req struct {
    ID string `path:"id" example:"123"` 
}
type Resp struct {
    Name string `json:"name"` 
}

op.AddReqStructure(new(Req))
op.AddRespStructure(new(Resp), func(cu *openapi.ContentUnit) { cu.HTTPStatus = http.StatusOK })

reflector.AddOperation(op)

schema, _ := reflector.Spec.MarshalYAML()
fmt.Println(string(schema))

The SanitizeMethodPath function validates an HTTP method and cleans up path patterns. It is particularly useful for converting router-style paths (like those in gorilla/mux) into standard OpenAPI path templates.

It performs the following:

1. Converts the method to lowercase.
2. Validates the method against standard HTTP verbs (get, put, post, delete, options, head, patch, trace).
3. Extracts path parameters (e.g., {id}) and removes regex-style constraints (e.g., {id:[0-9]+} becomes {id}).

Returns:

• cleanMethod: The lowercase HTTP method.
• cleanPath: The sanitized path pattern.
• pathParams: A slice of the extracted parameter names.
• err: An error if the method is invalid.

method := "GET"
path := "/users/{id:[0-9]+}"

cleanMethod, cleanPath, pathParams, err := openapi.SanitizeMethodPath(method, path)
// cleanMethod: "get"
// cleanPath: "/users/{id}"
// pathParams: []string{"id"}

The OperationContext interface is the central hub for defining and managing an OpenAPI operation. It combines information about the operation (tags, summary, description), the request/response structures, and the current processing state.

Key Capabilities:

• Metadata: Set tags, summary, description, and operation ID via OperationInfo methods.
• Structure Definition: Use AddReqStructure(i interface{}, options ...ContentOption) to define request bodies and AddRespStructure(o interface{}, options ...ContentOption) for responses.
• Security: Use AddSecurity(securityName string, scopes ...string) to define security requirements.
• State Tracking: Use OperationState methods to track if the system is currently processing a request or a response, and which part of the HTTP message (In) is being processed.

// Conceptual usage of OperationContext
func DefineOperation(ctx openapi.OperationContext) {
    ctx.SetSummary("Get User")
    ctx.SetTags("Users")
    
    // Define a request body
    ctx.AddReqStructure(UserRequest{}, openapi.WithContentType("application/json"))
    
    // Define a successful response
    ctx.AddRespStructure(UserResponse{}, openapi.WithHTTPStatus(200))
}

The SpecSchema interface is the primary abstraction for defining OpenAPI specifications in this library. It is designed to generalize across different OpenAPI revisions. It provides methods to manage basic metadata (Title, Description, Version) and to configure various security schemes.

To use it, you interact with the following methods:

Metadata Management

• Title() string: Retrieves the specification title.
• SetTitle(t string): Sets the specification title.
• Description() string: Retrieves the specification description.
• SetDescription(d string): Sets the specification description.
• Version() string: Retrieves the specification version.
• SetVersion(v string): Sets the specification version.

Security Configuration

• SetHTTPBasicSecurity(securityName string, description string): Configures HTTP Basic authentication.
• SetAPIKeySecurity(securityName string, fieldName string, fieldIn In, description string): Configures API Key authentication. Requires a fieldName and a fieldIn (of type In).
• SetHTTPBearerTokenSecurity(securityName string, format string, description string): Configures HTTP Bearer Token authentication.

// Example usage of SpecSchema methods
func configureSpec(spec SpecSchema) {
	spec.SetTitle("My API")
	spec.SetDescription("An example API specification")
	spec.SetVersion("1.0.0")

	// Configure security
	spec.SetHTTPBearerTokenSecurity("bearerAuth", "JWT", "Use a JWT token")
}

The JSONSchemaWalker interface allows you to traverse the JSON schemas extracted from a ContentUnit (which represents the body/content of an OpenAPI request or response). This is useful for custom validation or schema inspection.

Methods:

• WalkRequestJSONSchemas(method string, cu ContentUnit, cb JSONSchemaCallback, done func(oc OperationContext)) error: Iterates through schemas associated with a specific HTTP method in a request content unit.
• WalkResponseJSONSchemas(cu ContentUnit, cb JSONSchemaCallback, done func(oc OperationContext)) error: Iterates through schemas associated with a response content unit.
• ResolveJSONSchemaRef(ref string) (s jsonschema.SchemaOrBool, found bool): Resolves a specific JSON schema reference string to its schema object.

// Example of walking schemas with a callback
err := walker.WalkRequestJSONSchemas("POST", contentUnit, func(in openapi.In, paramName string, schema *jsonschema.SchemaOrBool, required bool) error {
    // Perform custom logic on each schema found
    fmt.Printf("Found parameter: %s, required: %v\n", paramName, required)
    return nil
}, func(oc openapi.OperationContext) {
    // Finalize operation
})

The Reflector interface is the primary entry point for converting Go structures into OpenAPI/JSON schemas. It extends JSONSchemaWalker, allowing you to not only extract schemas but also walk through request and response schemas for validation or inspection.

Key capabilities include:

• SpecSchema(): Returns the schema for the OpenAPI specification itself.
• JSONSchemaReflector(): Provides access to the underlying *jsonschema.Reflector for direct JSON Schema operations.
• AddOperation(oc OperationContext): Registers an operation context (method and path) to the reflector.

// Example of how a Reflector might be used (conceptual based on interface)
var reflector openapi.Reflector

// Register an operation
oc, _ := openapi.NewOperationContext("GET", "/users/{id}")
err := reflector.AddOperation(oc)

// Access the underlying JSON Schema reflector
jsReflector := reflector.JSONSchemaReflector()