Skip to content

Commit

Permalink
Improve swagger
Browse files Browse the repository at this point in the history
  • Loading branch information
Loïc Knuchel committed Jan 7, 2024
1 parent 1fe10d0 commit 4959d6e
Show file tree
Hide file tree
Showing 11 changed files with 430 additions and 104 deletions.
3 changes: 3 additions & 0 deletions backend/lib/azimutt/accounts/user_auth_token.ex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ defmodule Azimutt.Accounts.UserAuthToken do
use Azimutt.Schema
import Ecto.Changeset
alias Azimutt.Accounts.User
alias Azimutt.Utils.Uuid

schema "user_auth_tokens" do
belongs_to :user, User
Expand Down Expand Up @@ -32,4 +33,6 @@ defmodule Azimutt.Accounts.UserAuthToken do
token
|> cast(%{deleted_at: now}, [:deleted_at])
end

def is_valid?(value), do: Uuid.is_valid?(value)
end
39 changes: 0 additions & 39 deletions backend/lib/azimutt_web/controllers/api/gallery_controller.ex
View file
Original file line number Diff line number Diff line change
@@ -1,48 +1,9 @@
defmodule AzimuttWeb.Api.GalleryController do
use AzimuttWeb, :controller
use PhoenixSwagger
alias Azimutt.Gallery
action_fallback AzimuttWeb.Api.FallbackController

swagger_path :index do
get("/gallery")
summary("List sample projects")
description("List sample projects")
produces("application/json")
tag("Samples")

response(200, "OK", Schema.ref(:Samples))
response(400, "Client Error")
end

def index(conn, _params) do
conn |> render("index.json", samples: Gallery.list_samples())
end

def swagger_definitions do
%{
Sample:
swagger_schema do
title("Sample")
description("A Sample project")

properties do
slug(:string, "Sample slug", required: true)
color(:string, "Sample color", required: true)
icon(:string, "Sample icon", required: true)
name(:string, "Project name", required: true)
description(:string, "Project description", required: true)
project_id(:string, "Project id", required: true)
nb_tables(:integer, "Nb project tables", required: true)
end
end,
Samples:
swagger_schema do
title("Samples")
description("A collection of Samples")
type(:array)
items(Schema.ref(:Sample))
end
}
end
end
38 changes: 14 additions & 24 deletions backend/lib/azimutt_web/controllers/api/metadata_controller.ex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,11 @@ defmodule AzimuttWeb.Api.MetadataController do
tag("Metadata")
summary("Get project metadata")
description("Get all metadata for the project, ie all notes and tags for all tables and columns.")
produces("application/json")
get("#{SwaggerCommon.project_path()}/metadata")
SwaggerCommon.authorization()
SwaggerCommon.project_params()

response(200, "OK", Schema.ref(:ProjectMetadata))
response(200, "OK", Schema.ref(:Metadata))
response(400, "Client Error")
end

Expand All @@ -33,16 +32,15 @@ defmodule AzimuttWeb.Api.MetadataController do
tag("Metadata")
summary("Update project metadata")
description("Set the whole project metadata at once. Fetch it, update it then update it. Beware to not override changes made by others.")
produces("application/json")
put("#{SwaggerCommon.project_path()}/metadata")
SwaggerCommon.authorization()
SwaggerCommon.project_params()

parameters do
payload(:body, :object, "Project Metadata", required: true, schema: Schema.ref(:ProjectMetadata))
payload(:body, :object, "Project Metadata", required: true, schema: Schema.ref(:Metadata))
end

response(200, "OK", Schema.ref(:ProjectMetadata))
response(200, "OK", Schema.ref(:Metadata))
response(400, "Client Error")
end

Expand All @@ -59,7 +57,6 @@ defmodule AzimuttWeb.Api.MetadataController do
tag("Metadata")
summary("Get table metadata")
description("Get all metadata for the table, notes and tags. You can include columns metadata too with the `expand` query param.")
produces("application/json")
get("#{SwaggerCommon.project_path()}/tables/{table_id}/metadata")
SwaggerCommon.authorization()
SwaggerCommon.project_params()
Expand All @@ -69,7 +66,7 @@ defmodule AzimuttWeb.Api.MetadataController do
expand(:query, :array, "Expand columns metadata", collectionFormat: "csv", items: %{type: "string", enum: ["columns"]})
end

response(200, "OK", Schema.ref(:TableMetadata))
response(200, "OK", Schema.ref(:MetadataTable))
response(400, "Client Error")
end

Expand All @@ -83,17 +80,16 @@ defmodule AzimuttWeb.Api.MetadataController do
tag("Metadata")
summary("Update table metadata")
description("Set table metadata. If you include columns, they will be replaced, otherwise they will stay the same.")
produces("application/json")
put("#{SwaggerCommon.project_path()}/tables/{table_id}/metadata")
SwaggerCommon.authorization()
SwaggerCommon.project_params()

parameters do
table_id(:path, :string, "Id of the table (ex: public.users)", required: true)
payload(:body, :object, "Table Metadata", required: true, schema: Schema.ref(:TableMetadata))
payload(:body, :object, "Table Metadata", required: true, schema: Schema.ref(:MetadataTable))
end

response(200, "OK", Schema.ref(:TableMetadata))
response(200, "OK", Schema.ref(:MetadataTable))
response(400, "Client Error")
end

Expand All @@ -117,7 +113,6 @@ defmodule AzimuttWeb.Api.MetadataController do
tag("Metadata")
summary("Get column metadata")
description("Get all metadata for the column, notes and tags. For nested columns, use the column path (ex: details:address:street).")
produces("application/json")
get("#{SwaggerCommon.project_path()}/tables/{table_id}/columns/{column_path}/metadata")
SwaggerCommon.authorization()
SwaggerCommon.project_params()
Expand All @@ -127,7 +122,7 @@ defmodule AzimuttWeb.Api.MetadataController do
column_path(:path, :string, "Path of the column (ex: id, name or details:location)", required: true)
end

response(200, "OK", Schema.ref(:ColumnMetadata))
response(200, "OK", Schema.ref(:MetadataColumn))
response(400, "Client Error")
end

Expand All @@ -141,18 +136,17 @@ defmodule AzimuttWeb.Api.MetadataController do
tag("Metadata")
summary("Update column metadata")
description("Set column metadata. For nested columns, use the column path (ex: details:address:street).")
produces("application/json")
put("#{SwaggerCommon.project_path()}/tables/{table_id}/columns/{column_path}/metadata")
SwaggerCommon.authorization()
SwaggerCommon.project_params()

parameters do
table_id(:path, :string, "Id of the table (ex: public.users)", required: true)
column_path(:path, :string, "Path of the column (ex: id, name or details:location)", required: true)
payload(:body, :object, "Column Metadata", required: true, schema: Schema.ref(:ColumnMetadata))
payload(:body, :object, "Column Metadata", required: true, schema: Schema.ref(:MetadataColumn))
end

response(200, "OK", Schema.ref(:ColumnMetadata))
response(200, "OK", Schema.ref(:MetadataColumn))
response(400, "Client Error")
end

Expand All @@ -167,12 +161,10 @@ defmodule AzimuttWeb.Api.MetadataController do

def swagger_definitions do
%{
ProjectMetadata:
Metadata:
swagger_schema do
title("ProjectMetadata")
description("All Metadata of the project")
type(:object)
additional_properties(Schema.ref(:TableMetadata))
additional_properties(Schema.ref(:MetadataTable))

example(%{
"public.users": %{
Expand All @@ -194,15 +186,14 @@ defmodule AzimuttWeb.Api.MetadataController do
}
})
end,
TableMetadata:
MetadataTable:
swagger_schema do
title("TableMetadata")
description("The Metadata used to document tables")

properties do
notes(:string, "Markdown text to document the table", example: "*Table* notes")
tags(:array, "Tags to categorize the table", items: %{type: :string}, example: ["table-tag"])
columns(:object, "Columns metadata", additionalProperties: Schema.ref(:ColumnMetadata))
columns(:object, "Columns metadata", additionalProperties: Schema.ref(:MetadataColumn))
end

example(%{
Expand All @@ -220,9 +211,8 @@ defmodule AzimuttWeb.Api.MetadataController do
}
})
end,
ColumnMetadata:
MetadataColumn:
swagger_schema do
title("ColumnMetadata")
description("The Metadata used to document columns")

properties do
Expand Down
35 changes: 35 additions & 0 deletions backend/lib/azimutt_web/controllers/api/organization_controller.ex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,20 @@ defmodule AzimuttWeb.Api.OrganizationController do
alias Azimutt.Tracking
alias Azimutt.Utils.Result
alias AzimuttWeb.Utils.CtxParams
alias AzimuttWeb.Utils.SwaggerCommon
action_fallback AzimuttWeb.Api.FallbackController

swagger_path :index do
tag("Organizations")
summary("List user organizations")
description("Get the list of all organizations the user is part of.")
get("/organizations")
SwaggerCommon.authorization()

response(200, "OK", Schema.ref(:Organizations))
response(400, "Client Error")
end

def index(conn, params) do
current_user = conn.assigns.current_user
ctx = CtxParams.from_params(params)
Expand Down Expand Up @@ -40,4 +52,27 @@ defmodule AzimuttWeb.Api.OrganizationController do
conn |> render("table_colors.json", tweet: tweet, errors: errors)
end
end

def swagger_definitions do
%{
Organization:
swagger_schema do
description("An Organization in Azimutt")

properties do
id(:string, "Unique identifier", required: true, example: "0ed17b9f-cb2c-403a-a148-03215b73deb4")
slug(:string, "Organization slug", required: true, example: "azimutt")
name(:string, "Organization name", required: true, example: "Azimutt")
logo(:string, "Organization logo", example: "https://azimutt.app/images/logo_icon_dark.svg")
description(:string, "Organization description", example: "The best database explorer for any database!")
end
end,
Organizations:
swagger_schema do
description("A collection of Organizations")
type(:array)
items(Schema.ref(:Organization))
end
}
end
end
65 changes: 38 additions & 27 deletions backend/lib/azimutt_web/controllers/api/project_controller.ex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,26 +6,40 @@ defmodule AzimuttWeb.Api.ProjectController do
alias Azimutt.Projects
alias Azimutt.Projects.Project
alias AzimuttWeb.Utils.CtxParams
alias AzimuttWeb.Utils.SwaggerCommon
action_fallback AzimuttWeb.Api.FallbackController

swagger_path :index do
get("/projects")
summary("Query for projects")
description("Query for projects. This operation supports with paging and filtering")
produces("application/json")
tag("Projects")
summary("List organization projects")
description("Get the list of all projects in the organization.")
get("#{SwaggerCommon.organization_path()}/projects")
SwaggerCommon.authorization()
SwaggerCommon.organization_params()

response(200, "OK", Schema.ref(:Projects))
response(400, "Client Error")
end

def index(conn, %{"organization_id" => organization_id}) do
def index(conn, %{"organization_organization_id" => organization_id}) do
current_user = conn.assigns.current_user

with {:ok, %Organization{} = organization} <- Organizations.get_organization(organization_id, current_user),
do: conn |> render("index.json", projects: organization.projects, current_user: current_user)
end

swagger_path :show do
tag("Projects")
summary("Get a project")
description("Fetch the required project.")
get(SwaggerCommon.project_path())
SwaggerCommon.authorization()
SwaggerCommon.project_params()

response(200, "OK", Schema.ref(:Project))
response(400, "Client Error")
end

def show(conn, %{"organization_id" => _organization_id, "project_id" => project_id} = params) do
now = DateTime.utc_now()
maybe_current_user = conn.assigns.current_user
Expand All @@ -35,17 +49,6 @@ defmodule AzimuttWeb.Api.ProjectController do
do: conn |> render("show.json", project: project, maybe_current_user: maybe_current_user, ctx: ctx)
end

swagger_path :create do
post("/organizations/:organization_id/projects")
summary("Create a project")
description("TODO")
produces("application/json")
tag("Projects")

response(201, "Created")
response(400, "Client Error")
end

def create(conn, %{"organization_organization_id" => organization_id} = params) do
current_user = conn.assigns.current_user
ctx = CtxParams.from_params(params)
Expand Down Expand Up @@ -81,24 +84,32 @@ defmodule AzimuttWeb.Api.ProjectController do
%{
Project:
swagger_schema do
title("Project")
description("An Azimutt project")

properties do
name(:string, "Project name", required: true)
id(:string, "Unique identifier", required: true)
slug(:string, "Project slug")
id(:string, "Unique identifier", required: true, example: "a2cf8a87-0316-40eb-98ce-72659dae9420")
slug(:string, "Project slug", required: true, example: "azimutt-dev")
name(:string, "Project name", required: true, example: "Azimutt dev")
description(:string, "Project description", example: "Explore the Azimutt local database")
encoding_version(:integer, "Project storage version", required: true, example: 2)
storage_kind(:string, "Project storage kind", enum: ["local", "remote"], required: true, example: "local")
visibility(:string, "If the project is publicly visible", enum: ["none", "read", "write"], required: true, example: "read")
nb_sources(:integer, "Number of sources in the project", required: true, example: 2)
nb_tables(:integer, "Number of tables in the project", required: true, example: 563)
nb_columns(:integer, "Number of columns in the project", required: true, example: 13_945)
nb_relations(:integer, "Number of relations in the project", required: true, example: 2524)
nb_types(:integer, "Number of custom types in the project", required: true, example: 4)
nb_comments(:integer, "Number of SQL comments in the project", required: true, example: 892)
nb_layouts(:integer, "Number of layouts in the project", required: true, example: 32)
nb_notes(:integer, "Number of notes in the project", required: true, example: 3264)
nb_memos(:integer, "Number of memos in the project", required: true, example: 183)
created_at(:string, "When the project was created", format: "date-time", required: true, example: "2023-05-12T06:56:41.467400Z")
updated_at(:string, "The last time the project was updated", format: "date-time", required: true, example: "2023-06-28T14:43:12.345289Z")
archived_at(:string, "When the project was archived", format: "date-time", example: "2024-01-07T07:55:12.174780Z")
end

example(%{
name: "Project name",
id: "123",
slug: "project-name"
})
end,
Projects:
swagger_schema do
title("Projects")
description("A collection of Projects")
type(:array)
items(Schema.ref(:Project))
Expand Down
Loading

0 comments on commit 4959d6e

Please sign in to comment.