Build-time markdown generation with template slots for OpenAPI operations

[coderabbitai]

Summary

Currently, vitepress-openapi provides Vue components that read OpenAPI specs and render them at runtime. This approach has several limitations:

• All processing happens at runtime, which is not ideal for performance
• SEO limitations due to runtime rendering
• Cannot utilize the built-in VitePress markdown renderer
• Cannot leverage VitePress's build-time optimizations

Proposed Solution

Implement a build-time process (similar to vitepress-jsdoc) that generates markdown files with template slots for OpenAPI operations. This would provide better performance, SEO, and consistency with VitePress's markdown processing.

Example Generated Markdown

For an OpenAPI operation like GET /users, the system would generate:

<OAOperation>

<template #title>
# GET /users
</template>

<template #description>
Optional extended description in CommonMark or HTML.
</template>

<template #responses>

<template #response-200>

<template #response-200-description>
A JSON array of user names
</template>

<template #response-200-content-application-json>
```json
[
  "user1",
  "user2"
]

```

Benefits

• Performance: Processing happens at build time instead of runtime
• SEO: Static markdown files are properly indexed
• Consistency: Can use VitePress's built-in markdown renderer
• Build optimizations: Leverage VitePress's build-time features

Implementation Considerations

Build vs Dev Mode

• Build time: Generate markdown files for optimal performance
• Dev mode: Keep current runtime behavior for live editing and development
• Remote specs: Current runtime behavior remains valid for remote specifications

Command Line Tool

Consider implementing as both:

1. Build-time integration
2. Standalone CLI tool (similar to vitepress-jsdoc) that can be run manually

Backwards Compatibility

• Maintain current Vue component approach for runtime scenarios
• Ensure smooth migration path for existing users

Related Issues

• Enhance UI customization options for components #274
• Performance issues #171
• Shiki instance not being reused #278

Discussion Context

This proposal emerged from discussions in PR #282 about improving markdown rendering and performance. The conversation highlighted the need for better integration with VitePress's built-in capabilities while maintaining flexibility for different use cases.

Next Steps

1. Research vitepress-jsdoc implementation patterns
2. Design the slot-based template system
3. Implement build-time markdown generation
4. Ensure dev mode compatibility
5. Create migration documentation