Generate API Documentation in build.rs

help
1

This is not related to docs.rs, I'm talking about a REST API, not a library

I was wondering, is using build.rs to generate docs for an API a good usage of it or should I steer clear and do it some way else?
for example, I'd have a trait that has a bunch of html-generating-related methods, and the build.rs would just use those methods on all structs that implement the trait in the project though this would require having these structs in a separate crate from the project itself, which is why I'm unsure whether it's a good idea.

2

Crates like utoipa use procedural macros for generating OpenAPI docs, rather than the build script.

3

Should've specified, my API is not OpenAPI compliant, for a number of reasons outside the scope of this post.

4

I was not trying to suggest you should use utoipa, but rather that their API might give you an idea on how to proceed with yours.

5

That makes sense, I'll look into it.

6

build.rs has a limitation that it's supposed to only write to a hidden OUT_DIR and not have any other side effects.

It may still work if you use build.rs to generate Rust code, include that in your lib, and then rely on rustdoc to generate the documentation from that, but that's probably not as web-api-oriented as you'd like.

If you can parse your API definition files yourself (with the help of syn maybe), you could write a regular Rust program that generates the docs.

1 Like
7

Yeah this was more what I was thinking. My build.rs already has different side effects (mostly sql related stuff) so I'm honestly not too worried at this point.

I thought I'd give in and just do it like other languages (and rustdoc itself) do and just parse comments or something of that sort.