Any plans to support API documentation generation via OpenAPI specification?

[yinxulai]

Hi there

I'm interested in using Vrite and wondering if there are any plans to support API documentation generation from OpenAPI (formerly Swagger) specifications? This would be very helpful for automatically generating and maintaining API documentation from our OpenAPI schema files.
Some potential benefits this feature could bring:

Automatic generation of API reference documentation from OpenAPI/Swagger files
Keeping API documentation in sync with the actual API implementation
Reduced manual documentation effort
Standard way to document REST APIs

Is this something on your roadmap? If so, I'd love to hear more about the planned implementation approach and timeline.

Thanks for considering this feature request!

[areknawo]

Hey there,
I was considering OpenAPI support before, but I'm still not entirely sure how it'd work with Vrite and especially Vrite's editor.

A feature like that fits better in the docs generation/publishing layer than in Vrite's primary app.
You can consider Vrite's API Docs as a proof of concept for that idea. It pulls content & its layout from Vrite API, and the other details for the endpoint from the OpenAPI file: https://docs.vrite.io/api/content-groups/

But this approach is limiting and a bit cumbersome to work with.

So, support for OpenAPI-generated content might actually make more sense at the editor level.
However, here I'll need to somehow "connect" both the auto-generated content and the user-created one.
Otherwise, any edits could get overwritten by OpenAPI sync.

This will likely require support for editable & non-editable areas, and some form of automated content generation from OpenAPI files (for both the entire content pieces & sections within existing pieces).

I might consider something like that after the v1 redesign of Vrite I'm currently working on. Then Vrite should be more flexible to potentially handle such a use case.

---

Question for you - if you've used Vrite, how would you like to see OpenAPI support implemented?

[yinxulai]

I'm searching for effective documentation tools for my company and discovered Vrite. I'm really impressed with what Vrite has accomplished! Your work is truly meaningful.
Our services include numerous APIs, which we currently maintain in OpenAPI format. I'm particularly interested in this aspect of documentation. However, I don't have specific suggestions for improvement at the moment. As you mentioned, it becomes quite challenging to design when documentation, editing, and rendering are separated and independent from each other.

[yinxulai]

One final question: Do you have any plans to support built-in simple documentation rendering/deployment?

[yinxulai]

If implemented, this could significantly increase Vrite's user base, as most users don't have deep customization needs for their documentation sites.

[areknawo]

For API docs, I can see Vrite supporting an APIEndpoint block in the editor.
Then, these blocks can be auto-generated by OpenAPI sync and edit-locked, apart from an area dedicated for some additional, Endpoint-related content when necessary.

As for the Docs sites - yes, this is certainly planned.
You'll be able to either use a built-in site hosting in Vrite Cloud or "eject" into API-powered SSG/SSR website.
No definitive ETA yet, but likely to come with v1 early next year.

[yinxulai]

Very nice, hope everything goes well for you