Fill in documentation

This commit is contained in:
Curtis McEnroe 2015-11-28 23:33:58 -05:00
parent 40e2916343
commit efbf433025
4 changed files with 55 additions and 9 deletions

View File

@ -9,6 +9,10 @@ use super::Token;
use super::error::{Error, Result, OAuth2Error, OAuth2ErrorCode};
/// OAuth 2.0 client.
///
/// Performs HTTP requests using the provided `hyper::Client`.
///
/// See [RFC6749 section 4.1](http://tools.ietf.org/html/rfc6749#section-4.1).
pub struct Client {
http_client: hyper::Client,
@ -116,13 +120,13 @@ impl Client {
}
site_constructors!{
#[doc = "Creates a Google OAuth 2.0 client."]
#[doc = "Creates a Google OAuth 2.0 client.\n\nSee [Using OAuth 2.0 to Access Google APIs](https://developers.google.com/identity/protocols/OAuth2)."]
google => (
"https://accounts.google.com/o/oauth2/auth",
"https://accounts.google.com/o/oauth2/token"
),
#[doc = "Creates a GitHub OAuth 2.0 client."]
#[doc = "Creates a GitHub OAuth 2.0 client.\n\nSee [OAuth, GitHub API](https://developer.github.com/v3/oauth/)."]
github => (
"https://github.com/login/oauth/authorize",
"https://github.com/login/oauth/access_token"
@ -130,6 +134,8 @@ impl Client {
}
/// Constructs an authorization request URI.
///
/// See [RFC6749 section 4.1.1](http://tools.ietf.org/html/rfc6749#section-4.1.1).
pub fn auth_uri(&self, scope: Option<&str>, state: Option<&str>) -> Result<String> {
let mut uri = try!(Url::parse(&self.auth_uri));
@ -195,6 +201,8 @@ impl Client {
}
/// Requests an access token using an authorization code.
///
/// See [RFC6749 section 4.1.3](http://tools.ietf.org/html/rfc6749#section-4.1.3).
pub fn request_token(&self, code: &str) -> Result<Token> {
let mut body_pairs = vec![
("grant_type", "authorization_code"),
@ -208,6 +216,8 @@ impl Client {
/// Refreshes an access token.
///
/// See [RFC6749 section 6](http://tools.ietf.org/html/rfc6749#section-6).
///
/// # Panics
///
/// Panics if `token` does not contain a `refresh_token`.

View File

@ -5,24 +5,50 @@ use rustc_serialize::json;
use url;
/// OAuth 2.0 error codes.
///
/// See [RFC6749 section 5.2](http://tools.ietf.org/html/rfc6749#section-5.2).
#[derive(Debug)]
pub enum OAuth2ErrorCode {
/// The request is missing a required parameter, includes an unsupported parameter value (other
/// than grant type), repeats a parameter, includes multiple credentials, utilizes more than
/// one mechanism for authenticating the client, or is otherwise malformed.
InvalidRequest,
/// Client authentication failed (e.g., unknown client, no client authentication included, or
/// unsupported authentication method).
InvalidClient,
/// The provided authorization grant (e.g., authorization code, resource owner credentials) or
/// refresh token is invalid, expired, revoked, does not match the redirection URI used in the
/// authorization request, or was issued to another client.
InvalidGrant,
/// The authenticated client is not authorized to use this authorization grant type.
UnauthorizedClient,
/// The authorization grant type is not supported by the authorization server.
UnsupportedGrantType,
/// The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the
/// resource owner.
InvalidScope,
/// An unrecognized error code, not defined in RFC6749.
Unrecognized(String),
}
/// OAuth 2.0 error.
///
/// See [RFC6749](http://tools.ietf.org/html/rfc6749#section-5.2).
/// See [RFC6749 section 5.2](http://tools.ietf.org/html/rfc6749#section-5.2).
#[derive(Debug)]
pub struct OAuth2Error {
/// Error code.
pub code: OAuth2ErrorCode,
/// Human-readable text providing additional information about the error.
pub description: Option<String>,
/// A URI identifying a human-readable web page with information about the error.
pub uri: Option<String>,
}

View File

@ -7,6 +7,8 @@
//! [crate]: https://crates.io/crates/inth-oauth2
//! [github]: https://github.com/programble/inth-oauth2
//!
//! Implementation of [RFC6749](http://tools.ietf.org/html/rfc6749).
//!
//! ## Providers
//!
//! `inth_oauth2` can be used with any OAuth 2.0 provider, but provides defaults for a few common
@ -30,12 +32,7 @@
//! ```
//! use inth_oauth2::Client as OAuth2;
//!
//! let auth = OAuth2::github(
//! Default::default(),
//! "CLIENT_ID",
//! "CLIENT_SECRET",
//! None
//! );
//! let auth = OAuth2::github(Default::default(), "CLIENT_ID", "CLIENT_SECRET", None);
//! ```
//!
//! ### Other

View File

@ -1,12 +1,25 @@
use chrono::{DateTime, UTC};
/// OAuth 2.0 access token.
///
/// See [RFC6749 section 5](http://tools.ietf.org/html/rfc6749#section-5).
#[derive(Debug)]
pub struct Token {
/// The access token issued by the authorization server.
pub access_token: String,
/// The type of the token issued.
///
/// See [RFC6749 section 7.1](http://tools.ietf.org/html/rfc6749#section-7.1).
pub token_type: String,
/// The expiry time of the access token.
pub expires: Option<DateTime<UTC>>,
/// The refresh token, which can be used to obtain new access tokens.
pub refresh_token: Option<String>,
/// The scope of the access token.
pub scope: Option<String>,
}