improved docs on response types

Author: Heliozoa

tmc-client/src/lib.rs

@@ -22,8 +22,8 @@ pub use self::response::{
     Course, CourseData, CourseDataExercise, CourseDataExercisePoint, CourseDetails, CourseExercise,
     Exercise, ExerciseDetails, ExercisesDetails, NewSubmission, Organization, Review, Submission,
     SubmissionFeedbackResponse, SubmissionFinished, SubmissionProcessingStatus, SubmissionStatus,
-    UpdateResult, User,
+    User,
 };
-pub use self::tmc_client::{api_v8, ClientUpdateData, TmcClient, Token};
+pub use self::tmc_client::{api_v8, ClientUpdateData, TmcClient, Token, UpdateResult};
 pub use oauth2;
 pub use tmc_langs_plugins::{Language, RunResult, StyleValidationResult, StyleValidationStrategy};

tmc-client/src/response.rs

@@ -25,13 +25,18 @@ pub struct ErrorResponse {
     pub obsolete_client: bool,
 }
 
-/// OAuth2 credentials
+/// OAuth2 credentials.
+/// get /api/v8/application/{client_name}/credentials
 #[derive(Debug, Deserialize)]
 pub struct Credentials {
     pub application_id: String,
     pub secret: String,
 }
 
+/// get /api/v8/users/{user_id}
+/// get /api/v8/users/current
+/// post /api/v8/users/basic_info_by_usernames
+/// post /api/v8/users/basic_info_by_emails
 #[derive(Debug, Deserialize)]
 pub struct User {
     pub id: u32,
@@ -40,7 +45,8 @@ pub struct User {
     pub administrator: bool,
 }
 
-/// Organization information.
+/// get /api/v8/org.json
+/// get /api/v8/org/{organization_slug}.json
 #[derive(Debug, Serialize, Deserialize, JsonSchema)]
 pub struct Organization {
     pub name: String,
@@ -50,7 +56,7 @@ pub struct Organization {
     pub pinned: bool,
 }
 
-/// Information for a course.
+/// get /api/v8/core/org/{organization_slug}/courses
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct Course {
     pub id: u32,
@@ -64,7 +70,8 @@ pub struct Course {
     pub spyware_urls: Vec<String>,
 }
 
-/// Data for a course.
+/// get /api/v8/courses/{course_id}
+/// get /api/v8/org/{organization_slug}/courses/{course_name}
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct CourseData {
     pub name: String,
@@ -106,7 +113,7 @@ struct CourseDetailsInner {
     pub exercises: Vec<Exercise>,
 }
 
-/// Details for a course.
+/// get /api/v8/core/courses/{course_id}
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 #[serde(from = "CourseDetailsWrapper")]
 pub struct CourseDetails {
@@ -154,7 +161,7 @@ pub struct Exercise {
     pub solution_zip_url: Option<String>,
 }
 
-/// Exercise for a course.
+/// get /api/v8/courses/{course_id}/exercises
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct CourseExercise {
     pub id: u32,
@@ -169,6 +176,7 @@ pub struct CourseExercise {
     pub unlocked: bool,
 }
 
+/// get /api/v8/org/{organization_slug}/courses/{course_name}/exercises
 #[derive(Debug, Deserialize)]
 pub struct CourseDataExercise {
     pub id: u32,
@@ -188,6 +196,16 @@ pub struct ExercisePoint {
     pub requires_review: bool,
 }
 
+/// get /api/v8/courses/{course_id}/points
+/// get /api/v8/courses/{course_id}/exercises/{exercise_name}/points
+/// get /api/v8/courses/{course_id}/exercises/{exercise_name}/users/{user_id}/
+/// get /api/v8/courses/{course_id}/exercises/{exercise_name}/users/current/points
+/// get /api/v8/courses/{course_id}/users/{user_id}/points
+/// get /api/v8/courses/{course_id}/users/current/points
+/// get /api/v8/org/{organization_slug}/courses/{course_name}/points
+/// get /api/v8/org/{organization_slug}/courses/{course_name}/exercises/{exercise_name}/points
+/// get /api/v8/org/{organization_slug}/courses/{course_name}/users/{user_id}/points
+/// get /api/v8/org/{organization_slug}/courses/{course_name}/users/current/points
 #[derive(Debug, Deserialize)]
 pub struct CourseDataExercisePoint {
     awarded_point: AwardedPoint,
@@ -204,7 +222,7 @@ pub struct AwardedPoint {
     created_at: DateTime<FixedOffset>,
 }
 
-/// Details for an exercise.
+/// get /api/v8/core/exercises/{exercise_id}
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct ExerciseDetails {
     pub course_name: String,
@@ -218,6 +236,7 @@ pub struct ExerciseDetails {
     pub submissions: Vec<ExerciseSubmission>,
 }
 
+/// get /api/v8/core/exercises/details
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct ExercisesDetails {
     pub id: u32,
@@ -226,7 +245,16 @@ pub struct ExercisesDetails {
     pub checksum: String,
 }
 
-/// Exercise submission.
+/// get /api/v8/courses/{course_id}/submissions
+/// get /api/v8/courses/{course_id}/users/{user_id}/submissions
+/// get /api/v8/courses/{course_id}/users/current/submissions
+/// get api/v8/exercises/{exercise_id}/users/{user_id}/submissions
+/// get api/v8/exercises/{exercise_id}/users/current/submissions
+/// get /api/v8/org/{organization_slug}/courses/{course_name}/submissions
+/// get /api/v8/org/{organization_slug}/courses/{course_name}/users/{user_id}/submissions
+/// get /api/v8/org/{organization_slug}/courses/{course_name}/users/current/submissions
+/// get api/v8/exercises/{exercise_id}/users/{user_id}/submissions
+/// get api/v8/exercises/{exercise_id}/users/current/submissions
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct Submission {
     pub id: u32,
@@ -271,14 +299,15 @@ pub struct ExerciseSubmission {
     pub requests_review: bool,
 }
 
-/// Exercise submission.
+/// post /api/v8/core/exercises/{exercise_id}/submissions
 #[derive(Debug, Deserialize, Serialize, JsonSchema, Clone)]
 pub struct NewSubmission {
     pub show_submission_url: String,
     pub paste_url: String, // use Option and serde_with::string_empty_as_none ?
     pub submission_url: String,
 }
 
+/// get /api/v8/core/submission/{submission_id}
 #[derive(Debug, Deserialize, Serialize)]
 #[serde(untagged)] // TODO: tag
 pub enum SubmissionProcessingStatus {
@@ -300,7 +329,6 @@ pub enum SandboxStatus {
     ProcessingOnSandbox,
 }
 
-/// Finished submission.
 #[derive(Debug, Deserialize, Serialize, PartialEq, Eq, JsonSchema)]
 pub struct SubmissionFinished {
     pub api_version: u32,
@@ -338,7 +366,7 @@ pub enum SubmissionStatus {
     Hidden,
 }
 
-/// Response to feedback.
+/// post /api/v8/core/submissions/{submission_id}/feedback
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct SubmissionFeedbackResponse {
     pub api_version: u32,
@@ -431,7 +459,7 @@ impl<'de> Visitor<'de> for SubmissionFeedbackKindVisitor {
     }
 }
 
-/// Code review.
+/// get /api/v8/core/courses/{course_id}/reviews
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct Review {
     pub submission_id: u32,
@@ -448,13 +476,6 @@ pub struct Review {
     pub updated_at: DateTime<FixedOffset>,
 }
 
-/// Updated exercises.
-#[derive(Debug, Deserialize, Serialize, JsonSchema)]
-pub struct UpdateResult {
-    pub created: Vec<Exercise>,
-    pub updated: Vec<Exercise>,
-}
-
 #[cfg(test)]
 #[allow(clippy::clippy::unwrap_used)]
 mod test {

tmc-client/src/tmc_client.rs

@@ -10,6 +10,7 @@ use oauth2::{
     ResourceOwnerUsername, TokenUrl,
 };
 use reqwest::{blocking::Client, Url};
+use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
@@ -32,6 +33,13 @@ pub enum ClientUpdateData {
     PostedSubmission(NewSubmission),
 }
 
+/// Updated exercises.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct UpdateResult {
+    pub created: Vec<Exercise>,
+    pub updated: Vec<Exercise>,
+}
+
 /// A struct for interacting with the TestMyCode service, including authentication.
 #[derive(Clone)]
 pub struct TmcClient(Arc<TmcCore>);