actix/actix-website

Improve JSON response documentation

Closed this issue · 1 comments

JSON is the primary data format for RESTful service today. Yet the JSON response documentation is buried much later in the Responses page. Conversely items like form and multi-part requests that are not idiomatic for web services are surfaced much earlier. I will love to see the material re-organized so that JSON request and response comes earlier.

In addition, the JSON response example uses Result<HttpResponse> as the return type.

async fn index(obj: web::Path<MyObj>) -> Result<HttpResponse> {
    Ok(HttpResponse::Ok().json(MyObj {
        name: obj.name.to_string(),
    }))
}

While this works it is not strongly typed. A better example will be to use strong typing in return.

async fn index(req: HttpRequest) -> Result<web::Json<MyObj>> {
    Ok(web::Json(MyObj {
        name: String::from("Hello"),
    }))
}

I came across the same issue, and tried to solve it in #245. Plase let me know what you think about it.
However, going forward, I think we should rearrange the docs a little more drastically. We should probably mention how to return Json already in the Basics menu section, maybe in a new page called Responders? I can create another issue for it or send another PR if thats desired.