add openapi docs for all endpoints

Kab1r · Sep 11, 2024 · ac6bdba · ac6bdba
1 parent b976a58
commit ac6bdba
Show file tree

Hide file tree

Showing 10 changed files with 376 additions and 66 deletions.
diff --git a/api/src/db/publications.rs b/api/src/db/publications.rs
@@ -2,6 +2,7 @@ use std::{borrow::Cow, collections::HashMap};
 
 use serde::Serialize;
 use sqlx::{postgres::PgConnectOptions, Connection, Executor, PgConnection, Row};
+use utoipa::ToSchema;
 
 use super::tables::Table;
 
@@ -48,7 +49,7 @@ pub fn quote_literal(literal: &str) -> String {
     quoted_literal
 }
 
-#[derive(Serialize)]
+#[derive(Serialize, ToSchema)]
 pub struct Publication {
     pub name: String,
     pub tables: Vec<Table>,

diff --git a/api/src/routes/health_check.rs b/api/src/routes/health_check.rs
@@ -1,5 +1,10 @@
 use actix_web::{get, HttpResponse, Responder};
 
+#[utoipa::path(
+    responses(
+        (status = 200, description = "Api is healthy"),
+    )
+)]
 #[get("/health_check")]
 pub async fn health_check() -> impl Responder {
     HttpResponse::Ok().body("ok")

diff --git a/api/src/routes/images.rs b/api/src/routes/images.rs
@@ -8,6 +8,7 @@ use actix_web::{
 use serde::{Deserialize, Serialize};
 use sqlx::PgPool;
 use thiserror::Error;
+use utoipa::ToSchema;
 
 use crate::db;
 
@@ -53,24 +54,33 @@ impl ResponseError for ImageError {
     }
 }
 
-#[derive(Deserialize)]
-struct PostImageRequest {
+#[derive(Deserialize, ToSchema)]
+pub struct PostImageRequest {
+    #[schema(example = "supabase/replicator:1.2.3")]
     pub name: String,
+    #[schema(example = true)]
     pub is_default: bool,
 }
 
-#[derive(Serialize)]
-struct PostImageResponse {
+#[derive(Serialize, ToSchema)]
+pub struct PostImageResponse {
     id: i64,
 }
 
-#[derive(Serialize)]
-struct GetImageResponse {
+#[derive(Serialize, ToSchema)]
+pub struct GetImageResponse {
     id: i64,
     name: String,
     is_default: bool,
 }
 
+#[utoipa::path(
+    request_body = PostImageRequest,
+    responses(
+        (status = 200, description = "Create new image", body = PostImageResponse),
+        (status = 500, description = "Internal server error")
+    )
+)]
 #[post("/images")]
 pub async fn create_image(
     pool: Data<PgPool>,
@@ -82,6 +92,16 @@ pub async fn create_image(
     Ok(Json(response))
 }
 
+#[utoipa::path(
+    params(
+        ("image_id" = i64, Path, description = "Id of the image"),
+    ),
+    responses(
+        (status = 200, description = "Return image with id = image_id", body = GetImageResponse),
+        (status = 404, description = "Image not found"),
+        (status = 500, description = "Internal server error")
+    )
+)]
 #[get("/images/{image_id}")]
 pub async fn read_image(
     pool: Data<PgPool>,
@@ -99,6 +119,17 @@ pub async fn read_image(
     Ok(Json(response))
 }
 
+#[utoipa::path(
+    request_body = PostImageRequest,
+    params(
+        ("image_id" = i64, Path, description = "Id of the image"),
+    ),
+    responses(
+        (status = 200, description = "Update image with id = image_id"),
+        (status = 404, description = "Image not found"),
+        (status = 500, description = "Internal server error")
+    )
+)]
 #[post("/images/{image_id}")]
 pub async fn update_image(
     pool: Data<PgPool>,
@@ -112,6 +143,16 @@ pub async fn update_image(
     Ok(HttpResponse::Ok().finish())
 }
 
+#[utoipa::path(
+    params(
+        ("image_id" = i64, Path, description = "Id of the image"),
+    ),
+    responses(
+        (status = 200, description = "Delete image with id = image_id"),
+        (status = 404, description = "Image not found"),
+        (status = 500, description = "Internal server error")
+    )
+)]
 #[delete("/images/{image_id}")]
 pub async fn delete_image(
     pool: Data<PgPool>,
@@ -124,6 +165,12 @@ pub async fn delete_image(
     Ok(HttpResponse::Ok().finish())
 }
 
+#[utoipa::path(
+    responses(
+        (status = 200, description = "Return all images"),
+        (status = 500, description = "Internal server error")
+    )
+)]
 #[get("/images")]
 pub async fn read_all_images(pool: Data<PgPool>) -> Result<impl Responder, ImageError> {
     let mut sources = vec![];

diff --git a/api/src/routes/pipelines.rs b/api/src/routes/pipelines.rs
@@ -10,6 +10,7 @@ use actix_web::{
 use serde::{Deserialize, Serialize};
 use sqlx::PgPool;
 use thiserror::Error;
+use utoipa::ToSchema;
 
 use crate::{
     db::{
@@ -112,21 +113,21 @@ impl ResponseError for PipelineError {
     }
 }
 
-#[derive(Deserialize)]
-struct PostPipelineRequest {
+#[derive(Deserialize, ToSchema)]
+pub struct PostPipelineRequest {
     pub source_id: i64,
     pub sink_id: i64,
     pub publication_name: String,
     pub config: PipelineConfig,
 }
 
-#[derive(Serialize)]
-struct PostPipelineResponse {
+#[derive(Serialize, ToSchema)]
+pub struct PostPipelineResponse {
     id: i64,
 }
 
-#[derive(Serialize)]
-struct GetPipelineResponse {
+#[derive(Serialize, ToSchema)]
+pub struct GetPipelineResponse {
     id: i64,
     tenant_id: i64,
     source_id: i64,
@@ -151,6 +152,13 @@ fn extract_tenant_id(req: &HttpRequest) -> Result<i64, PipelineError> {
     Ok(tenant_id)
 }
 
+#[utoipa::path(
+    request_body = PostPipelineRequest,
+    responses(
+        (status = 200, description = "Create new pipeline", body = PostPipelineResponse),
+        (status = 500, description = "Internal server error")
+    )
+)]
 #[post("/pipelines")]
 pub async fn create_pipeline(
     req: HttpRequest,
@@ -188,6 +196,16 @@ pub async fn create_pipeline(
     Ok(Json(response))
 }
 
+#[utoipa::path(
+    params(
+        ("pipeline_id" = i64, Path, description = "Id of the pipeline"),
+    ),
+    responses(
+        (status = 200, description = "Return pipeline with id = pipeline_id", body = GetPipelineResponse),
+        (status = 404, description = "Pipeline not found"),
+        (status = 500, description = "Internal server error")
+    )
+)]
 #[get("/pipelines/{pipeline_id}")]
 pub async fn read_pipeline(
     req: HttpRequest,
@@ -217,6 +235,17 @@ pub async fn read_pipeline(
     Ok(Json(response))
 }
 
+#[utoipa::path(
+    request_body = PostSinkRequest,
+    params(
+        ("pipeline_id" = i64, Path, description = "Id of the pipeline"),
+    ),
+    responses(
+        (status = 200, description = "Update pipeline with id = pipeline_id"),
+        (status = 404, description = "Pipeline not found"),
+        (status = 500, description = "Internal server error")
+    )
+)]
 #[post("/pipelines/{pipeline_id}")]
 pub async fn update_pipeline(
     req: HttpRequest,
@@ -255,6 +284,16 @@ pub async fn update_pipeline(
     Ok(HttpResponse::Ok().finish())
 }
 
+#[utoipa::path(
+    params(
+        ("pipeline_id" = i64, Path, description = "Id of the pipeline"),
+    ),
+    responses(
+        (status = 200, description = "Delete pipeline with id = pipeline_id"),
+        (status = 404, description = "Pipeline not found"),
+        (status = 500, description = "Internal server error")
+    )
+)]
 #[delete("/pipelines/{pipeline_id}")]
 pub async fn delete_pipeline(
     req: HttpRequest,
@@ -269,6 +308,12 @@ pub async fn delete_pipeline(
     Ok(HttpResponse::Ok().finish())
 }
 
+#[utoipa::path(
+    responses(
+        (status = 200, description = "Return all pipelines"),
+        (status = 500, description = "Internal server error")
+    )
+)]
 #[get("/pipelines")]
 pub async fn read_all_pipelines(
     req: HttpRequest,

diff --git a/api/src/routes/sinks.rs b/api/src/routes/sinks.rs
@@ -8,6 +8,7 @@ use actix_web::{
 use serde::{Deserialize, Serialize};
 use sqlx::PgPool;
 use thiserror::Error;
+use utoipa::ToSchema;
 
 use crate::{
     db::{
@@ -71,19 +72,21 @@ impl ResponseError for SinkError {
     }
 }
 
-#[derive(Deserialize)]
-struct PostSinkRequest {
+#[derive(Deserialize, ToSchema)]
+pub struct PostSinkRequest {
     pub config: SinkConfig,
 }
 
-#[derive(Serialize)]
-struct PostSinkResponse {
+#[derive(Serialize, ToSchema)]
+pub struct PostSinkResponse {
     id: i64,
 }
 
-#[derive(Serialize)]
-struct GetSinkResponse {
+#[derive(Serialize, ToSchema)]
+pub struct GetSinkResponse {
+    #[schema(example = 1)]
     id: i64,
+    #[schema(example = 1)]
     tenant_id: i64,
     config: SinkConfig,
 }
@@ -101,6 +104,13 @@ fn extract_tenant_id(req: &HttpRequest) -> Result<i64, SinkError> {
     Ok(tenant_id)
 }
 
+#[utoipa::path(
+    request_body = PostSinkRequest,
+    responses(
+        (status = 200, description = "Create new sink", body = PostSinkResponse),
+        (status = 500, description = "Internal server error")
+    )
+)]
 #[post("/sinks")]
 pub async fn create_sink(
     req: HttpRequest,
@@ -116,6 +126,16 @@ pub async fn create_sink(
     Ok(Json(response))
 }
 
+#[utoipa::path(
+    params(
+        ("sink_id" = i64, Path, description = "Id of the sink"),
+    ),
+    responses(
+        (status = 200, description = "Return sink with id = sink_id", body = GetSourceResponse),
+        (status = 404, description = "Sink not found"),
+        (status = 500, description = "Internal server error")
+    )
+)]
 #[get("/sinks/{sink_id}")]
 pub async fn read_sink(
     req: HttpRequest,
@@ -136,6 +156,17 @@ pub async fn read_sink(
     Ok(Json(response))
 }
 
+#[utoipa::path(
+    request_body = PostSinkRequest,
+    params(
+        ("sink_id" = i64, Path, description = "Id of the sink"),
+    ),
+    responses(
+        (status = 200, description = "Update sink with id = sink_id"),
+        (status = 404, description = "Sink not found"),
+        (status = 500, description = "Internal server error")
+    )
+)]
 #[post("/sinks/{sink_id}")]
 pub async fn update_sink(
     req: HttpRequest,
@@ -154,6 +185,16 @@ pub async fn update_sink(
     Ok(HttpResponse::Ok().finish())
 }
 
+#[utoipa::path(
+    params(
+        ("sink_id" = i64, Path, description = "Id of the sink"),
+    ),
+    responses(
+        (status = 200, description = "Delete sink with id = sink_id"),
+        (status = 404, description = "Sink not found"),
+        (status = 500, description = "Internal server error")
+    )
+)]
 #[delete("/sinks/{sink_id}")]
 pub async fn delete_sink(
     req: HttpRequest,
@@ -168,6 +209,12 @@ pub async fn delete_sink(
     Ok(HttpResponse::Ok().finish())
 }
 
+#[utoipa::path(
+    responses(
+        (status = 200, description = "Return all sinks"),
+        (status = 500, description = "Internal server error")
+    )
+)]
 #[get("/sinks")]
 pub async fn read_all_sinks(
     req: HttpRequest,