Generate API documentation

[spacekookie]

I'm using actix-web to build a RESTful API in Rust, accepting various Json payloads on multiple routes and methods, etc.

It would be incredibly awesome if actix was able to generate documentation for these endpoints, possibly with some template that's used to generate html.

There are a few ways this could be implemented, but I'm opening this issue first mostly to see if there is interest in such a feature from the core developers.

[DoumanAsh]

I guess would kinda useful

Currently the only facilities for this currently is HttpRequest::url_for or HttpRequest::url_for_static
And that is pretty much limited.

But I imagine something that could generate help information from App would be quite.

But things like generating full fledged /help endpoint with nice looking description of REST API should be put into a separate crate.

[fafhrd91]

@spacekookie I think it would be extremely useful feature! If we could describe api we could export it as swagger spec, which would be awesome.

[glademiller]

I think generating swagger documentation would be my preferred auto documentation format because all the existing tooling.

[spacekookie]

So what would actually have to happen to make this happen? Aka, how many versions do I have to wait for it? 😬

[DJMcNab]

I want to try to work on it when I have some free time, but I'm very busy. The biggest hurdle has been solved when I found this stackoverflow question, which, when modified, should allow access to the extractor information of each route.

[sergeysova]

Has something progress?

[DJMcNab]

I have some progress on one for Rocket, but not for actix-web, sorry.

[spacekookie]

@DJMcNab How is that one implemented? Is there a crate that generates swagger or something like it? Because that work wouldn't need to be copied for actix-web

[DJMcNab]

It's slightly awkward because it's for a qualification - I can't give too much detail until about October :(, and especially not release any code until then.

[spacekookie]

Oh :( That's very unfortuante. That's very teasing then 😅

[sergeysova]

I started working on actix-rest

[glademiller]

I don't have anything to show from my experimenting but I have mostly been exploring the OpenAPI or something OpenAPI like to an Actix server so basically the opposite of what this is about. That said in my research I think something that would be essential to have for any framework would be a simple way to generate the OpenAPI schema definition based on serde annotations. I think that is one of the bigger pieces of this story. After that for actix-web in particular building extractors in such a way that they can be easily documented. I have some custom extractors I have built and I don't think we can support OpenAPI documentation generation from a custom extractor without someone to annotate the extractor directly to explain what parameters it is reading from. I'm going to continue exploring the space and if I every get around to building something more or less complete I will update my findings and ask for input.

[clearydude]

This would be a really useful feature. It looks like some people are trying to work on supporting this, but from what I can tell current actix really does not support getting any information from the App.
If there was some way that you could query the app for Routes, query the Routes for Path/Query params, that would likely facilitate further work on this.
Are there any suggestions now that 1.0 has been released other than the previous ones about url_for and url_for_static? Or any plans to include any of this in an upcoming release?

[sergeysova]

What about to generate code for actix from openapi 3.0 file?

[clearydude]

@sergeysova for my specific use case that wouldn't really be super helpful (although it might be for others). Also I believe that swagger-codegen can be used to generate client/server code in rust from an openapi spec which could then be adapted to actix-web but I haven't tried it out.
I am more interested in being able to generate specs from the code so that as the API changes within the code the openapi spec would also be programatically updated, ensuring consistency between the docs and the source code. We already have our API written with actix-web and are really happy with it but as it evolves it can pretty easily become out of date with the swagger docs if we forget to update, or if a different person is updating them. Generating this spec from the code (similar to how rustdoc generates doc pages from doc comments) would make this a non-issue.
If at least there were some ways that we could get this information out of the App or the HttpServer after the fact it would make doing this work more feasible, but as of 1.0 I'm not certain that it's even possible.

[jspeis]

☝️I agree with @clearydude. It would be really great to be able to write inline docs. Something like the way flasgger can use docstrings in Python to then generate an API spec, would be nice.

[onelson]

The prospect of generating a spec from an actix-web app is super exciting.

We're currently in the throes of developing a process for generating typescript definitions for the serde data we're responding with, and we are able to run conformance tests when our server code changes. A CI job uses the server to spit out a new .ts with the types in it, and we run the compiler over our frontend code using the new types to see if there are API contracts being broken where client code will need to be adjusted to fit.

If we were able to have our actix server spit out an openapi spec, we'd be able to effectively use this for snapshot testing of our public API, checking the spec against the previous release. Snapshot testing like this could help to drive effective versioning of the API. This would be a very powerful communication tool, even for small shops like mine, keeping the team in the loop as we go.

P.S, we are currently writing our specs independently by hand and rendering with ReDoc. It's basic but works for us. Likely if we got actix to generate a spec the way we'd like, we'd be doing it "offline" as a part of a docker build and spitting out the generated HTML to serve it as static files. That's our use case, at any rate.

[wafflespeanut]

Hey everyone! I've been working on OpenAPI-related tooling over the past few weeks - I'm not completely sure whether actix-web should stick to some specification such as OpenAPI v2/v3, so I thought I could try to come up with a plugin for hosting the spec, and I may have a solution (I'm still working on the proof of concept).

Taking this basic example:

use actix_web::{App, web};

#[derive(Deserialize, Serialize)]
pub struct Pet {
    name: String,
    id: Option<String>,
}

fn add_pet(body: web::Json<Counter>) -> web::Json<Counter> {
    body
}

let app = App::new()
    .service(web::resource("/pets").route(web::post().to(add_pet)));

Using the plugin, it'll become:

use actix_web::App;
use paperclip::actix::{web, prelude::*}; // feature gated

#[api_v2_schema]
#[derive(Deserialize, Serialize)]
pub struct Pet {
    name: String,
    id: Option<String>,
}

#[api_v2_operation]
fn add_pet(body: web::Json<Counter>) -> web::Json<Counter> {
    body
}

let app = App::new()
    .wrap_api() // keep track of all routes and operations from this line
    .with_json_spec_at("/api/spec")
    .service(web::resource("/pets").route(web::post().to(add_pet)))
    .build();

Other than the attributes on top of the handlers and models, the code will look pretty much exactly the same as the normal actix-web flow. WDYT?

NOTE: The signature for the handler used here is really basic, but that's not the limit of the plugin itself.

[fafhrd91]

@wafflespeanut looks pretty cool! if you want we can include section on actix.rs

[wafflespeanut]

@fafhrd91 That'd be great! Thank you! I think I'll have a working version by this weekend. I'll post my updates here :)

[clearydude]

@wafflespeanut This looks great! Thanks so much for sharing :) Excited to check it out

[wafflespeanut]

0Hi @fafhrd91! Would it be possible to expose Factory and AsyncFactory traits? (through dev module at least?). It's internal atm, but in order to wrap all struct methods, I need those traits. I waited all this time just to make sure I don't need anything else 😅 and I believe that's the only change I have (and some minor clippy fixes). If that's okay, I'll open a PR :)

(Progress update for everyone else! It's coming!)

[fafhrd91]

@wafflespeanut ok, but lets mark this traits as #[doc(hidden)] for now.

[wafflespeanut]

Hello everyone! I've just released paperclip 0.3.0 and it comes with the initial version of actix-web plugin for hosting OpenAPI v2 spec. It shouldn't break your actix-web flow. Please try it out!

Detailed example in https://paperclip.waffles.space/actix-plugin.html :)

[jonnius]

Is there a way to add doxygen like API docs for a RESTful API?

[polarathene]

@jonnius yes but not really in Rust atm afaik.

There are two plugins for having your server code output OpenAPI data, the paperclip project above for actix, and another WIP one for Rocket. I don't think either are at a point that they can use comments from your code to add to the documentation like Crates can. Paperclip also currently only supports OpenAPI v2(not that it should be a barrier for supporting descriptions).

If you don't need descriptions and just want to document the REST API endpoints along with parameters, then either of these may be sufficient. Otherwise, you may want to consider writing the OpenAPI files(YAML/JSON) and using a generator to output Rust code and take it from there(no idea what quality is like for such).

[glademiller]

One work around I have settled on since I wanted to move to stable and paperclip, at least at the time, didn't support stable is to use https://apidocjs.com/. It has the downside that it is just parsing comments and doesn't actually look at the code itself but it works quite well as a stop gap until we have something better in the future.

…

On Wed, Dec 11, 2019, 05:58 Brennan Kinney ***@***.***> wrote: @jonnius <https://github.com/jonnius> yes but not really in Rust atm afaik. There are two plugins for having your server code output OpenAPI data, the paperclip project above for actix, and another WIP one for Rocket. I don't think either are at a point that they can use comments from your code to add to the documentation like Crates can. Paperclip also currently only supports OpenAPI v2(not that it should be a barrier for supporting descriptions). If you don't need descriptions and just want to document the REST API endpoints along with parameters, then either of these may be sufficient. Otherwise, you may want to consider writing the OpenAPI files(YAML/JSON) and using a generator to output Rust code and take it from there(no idea what quality is like for such). — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#310?email_source=notifications&email_token=AAPJZBCGQSVRQ3UASSOXSR3QYDPVRA5CNFSM4FEXHRKKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEGTAHDY#issuecomment-564528015>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAPJZBEW3I6PSDGVBSXYOZTQYDPVRANCNFSM4FEXHRKA> .

[jonnius]

Thanks for the replies. I need to add descriptions to the API end points. Can apiDoc be used with Rust code? It's not listed on their website.

[glademiller]

It isn't listed and it won't detect thing automatically but if you explicitly tell it to look for .rs files and put the comments in /****** * */ Format like their js examples it works just fine since it is just parsing comments. It isn't a great solution but it does the job.

…

On Fri, Dec 13, 2019, 03:51 jonnius ***@***.***> wrote: Thanks for the replies. I need to add descriptions to the API end points. Can apiDoc be used with Rust code? It's not listed on their website. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#310?email_source=notifications&email_token=AAPJZBHMKFOSUZGJUPKC5Z3QYNSJ5A5CNFSM4FEXHRKKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEGZUEKQ#issuecomment-565396010>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAPJZBBVFTPCHGLUNT6N5G3QYNSJ5ANCNFSM4FEXHRKA> .

[Pzixel]

@wafflespeanut any plans on OpenApi 3.0?

[wafflespeanut]

@Pzixel In the upcoming release (0.4.0), I'm focusing on getting v2 polished (because that's used by majority of the web). In the next release, I'll be focusing on v3. It's tracked here. 😄

[patrickelectric]

It was add on https://github.com/paperclip-rs/paperclip: CHANGELOG

[bhoudebert]

A new crate emerged recently, which I found a really nice alternative when you are only looking for openapi generation: https://github.com/juhaku/utoipa

[wurikiji]

A new crate emerged recently, which I found a really nice alternative when you are only looking for openapi generation: https://github.com/juhaku/utoipa

This is what I've wanted.

[developomp]

I think it's safe to close this issue now that we have several projects that can easily generate API docs for actix.

[bk138]

Maybe most suited ones should be added to the actix docs as a pointer?

[satokenta940]

I've found Apidog highly effective for document generation. Check out their tutorial for detailed guidance: [How to Generate API Documentation Using Apidog]

[francesco-gaglione]

https://github.com/kurtbuilds/oasgen

It could be very nice to implement something like this into the actix framework itself

[ollyde]

I would also checkout Salvo as inspiration (https://salvo.rs/book/middlewares/openapi.html), the API docs are automatic, including all the return types.

It allows you to use Swagger TypeScript/Dart auto-api generator for front-end projects. Something that is not possible with this project without clunky manual Documentation adders like Apidog and Utopia (which result in human error)

@satokenta940 @wurikiji