From 5ca728e8f8c5ea26c07de237ba6231e4ea1928ff Mon Sep 17 00:00:00 2001 From: sureshms Date: Mon, 2 Aug 2021 14:21:59 -0700 Subject: [PATCH] Improve API documentation --- catalog-rest-service/pom.xml | 21 +++++++---------- .../catalog/jdbi3/DashboardRepository.java | 8 +++---- .../catalog/jdbi3/MetricsRepository.java | 8 +++---- .../catalog/jdbi3/ReportRepository.java | 8 +++---- .../catalog/resources/CatalogResource.java | 7 +++++- .../catalog/resources/bots/BotsResource.java | 5 +++- .../resources/config/ConfigResource.java | 13 ++++++++++- .../dashboards/DashboardResource.java | 11 +++++---- .../resources/databases/DatabaseResource.java | 11 ++++++++- .../resources/databases/TableResource.java | 23 +++++++++++++++---- .../catalog/resources/feeds/FeedResource.java | 7 ++++-- .../resources/metrics/MetricsResource.java | 11 +++++---- .../resources/pipelines/PipelineResource.java | 3 +++ .../resources/reports/ReportResource.java | 11 +++++---- .../resources/search/SearchResource.java | 9 +++++--- .../resources/services/ServiceResource.java | 1 + .../database/DatabaseServiceResource.java | 13 ++++++++--- .../catalog/resources/tags/TagResource.java | 21 +++++++++++++---- .../catalog/resources/teams/TeamResource.java | 8 +++++++ .../catalog/resources/teams/UserResource.java | 12 ++++++++-- .../resources/usage/UsageResource.java | 22 +++++++++++------- .../resources/version/VersionResource.java | 7 +++--- .../json/schema/entity/data/table.json | 3 ++- docs/openmetadata-apis/apis.md | 11 +++++---- 24 files changed, 174 insertions(+), 80 deletions(-) diff --git a/catalog-rest-service/pom.xml b/catalog-rest-service/pom.xml index 54373909036..8a14083cce4 100644 --- a/catalog-rest-service/pom.xml +++ b/catalog-rest-service/pom.xml @@ -337,24 +337,19 @@ - Open Metadata Apis - 1.0.0 - Terms + OpenMetadata Apis + 0.3.0 - e@mail.com - Open Metadata - https:/open-metadata.io + contact@open-metadata.org + OpenMetadata + https:/open-metadata.org - https://license - MIT + https://www.apache.org/licenses/LICENSE-2.0 + Apache 2.0 - - my-custom-field-1 - my-custom-field-2 - - src/test/resources/descriptions.md + ../docs/openmetadata-apis/apis.md diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/jdbi3/DashboardRepository.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/jdbi3/DashboardRepository.java index e1b968ea4c0..0e10c57a125 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/jdbi3/DashboardRepository.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/jdbi3/DashboardRepository.java @@ -95,8 +95,8 @@ public abstract class DashboardRepository { return setFields(EntityUtil.validate(id, dashboardDAO().findById(id), Dashboard.class), fields); } - public List list(Fields fields, String fqn) throws IOException { - List jsonList = dashboardDAO().list(fqn); + public List list(Fields fields) throws IOException { + List jsonList = dashboardDAO().list(); List dashboardList = new ArrayList<>(); for (String json : jsonList) { dashboardList.add(setFields(JsonUtils.readValue(json, Dashboard.class), fields)); @@ -171,7 +171,7 @@ public abstract class DashboardRepository { @SqlQuery("SELECT json FROM dashboard_entity WHERE fullyQualifiedName = :name") String findByFQN(@Bind("name") String name); - @SqlQuery("SELECT json FROM dashboard_entity WHERE (fullyQualifiedName = :name OR :name is NULL)") - List list(@Bind("name") String name); + @SqlQuery("SELECT json FROM dashboard_entity") + List list(); } } diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/jdbi3/MetricsRepository.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/jdbi3/MetricsRepository.java index 7912be5e888..d960d559d3d 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/jdbi3/MetricsRepository.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/jdbi3/MetricsRepository.java @@ -94,8 +94,8 @@ public abstract class MetricsRepository { } @Transaction - public List list(Fields fields, String fqn) throws IOException { - List jsonList = metricsDAO().list(fqn); + public List list(Fields fields) throws IOException { + List jsonList = metricsDAO().list(); List metricsList = new ArrayList<>(); for (String json : jsonList) { metricsList.add(setFields(JsonUtils.readValue(json, Metrics.class), fields)); @@ -168,8 +168,8 @@ public abstract class MetricsRepository { @SqlQuery("SELECT json FROM metric_entity WHERE fullyQualifiedName = :name") String findByFQN(@Bind("name") String name); - @SqlQuery("SELECT json FROM metric_entity WHERE (fullyQualifiedName = :name OR :name is NULL)") - List list(@Bind("name") String name); + @SqlQuery("SELECT json FROM metric_entity") + List list(); @SqlQuery("SELECT EXISTS (SELECT * FROM metric_entity where id = :id)") boolean exists(@Bind("id") String id); diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/jdbi3/ReportRepository.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/jdbi3/ReportRepository.java index 006f1a5e756..e56f010b8cd 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/jdbi3/ReportRepository.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/jdbi3/ReportRepository.java @@ -94,8 +94,8 @@ public abstract class ReportRepository { return setFields(EntityUtil.validate(id, reportDAO().findById(id), Report.class), fields); } - public List list(Fields fields, String fqn) throws IOException { - List jsonList = reportDAO().list(fqn); + public List list(Fields fields) throws IOException { + List jsonList = reportDAO().list(); List reportList = new ArrayList<>(); for (String json : jsonList) { reportList.add(setFields(JsonUtils.readValue(json, Report.class), fields)); @@ -168,8 +168,8 @@ public abstract class ReportRepository { @SqlQuery("SELECT json FROM report_entity WHERE fullyQualifiedName = :name") String findByFQN(@Bind("name") String name); - @SqlQuery("SELECT json FROM report_entity WHERE (name = :name OR :name is NULL)") - List list(@Bind("name") String name); + @SqlQuery("SELECT json FROM report_entity") + List list(); @SqlQuery("SELECT EXISTS (SELECT * FROM report_entity where id = :id)") boolean exists(@Bind("id") String id); diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/CatalogResource.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/CatalogResource.java index 9fb32cad0c5..d135d25d88c 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/CatalogResource.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/CatalogResource.java @@ -17,6 +17,7 @@ package org.openmetadata.catalog.resources; import com.fasterxml.jackson.core.JsonProcessingException; +import org.openmetadata.catalog.resources.databases.TableResource.TableList; import org.openmetadata.catalog.type.CollectionDescriptor; import io.swagger.annotations.Api; import io.swagger.v3.oas.annotations.Operation; @@ -25,6 +26,7 @@ import io.swagger.v3.oas.annotations.media.Schema; import io.swagger.v3.oas.annotations.responses.ApiResponse; import org.openmetadata.catalog.util.ResultList; +import javax.ws.rs.Consumes; import javax.ws.rs.GET; import javax.ws.rs.Path; import javax.ws.rs.Produces; @@ -37,6 +39,7 @@ import java.util.List; @Path("/v1") @Api(value = "All collections in the catalog application", tags = "All collections in the Catalog") @Produces(MediaType.APPLICATION_JSON) +@Consumes(MediaType.APPLICATION_JSON) @Collection(name = "root") public class CatalogResource { public static class CollectionList extends ResultList { @@ -59,7 +62,9 @@ public class CatalogResource { } @GET - @Operation(summary = "List all collections", tags = "", + @Operation(summary = "List all collections", tags = "general", + description = "List all the collections supported by OpenMetadata. This list provides all the collections " + + "and resource REST endpoints.", responses = { @ApiResponse(responseCode = "200", description = "All collections", content = @Content(mediaType = "application/json", diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/bots/BotsResource.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/bots/BotsResource.java index 28f8db3fd06..1d4d988a529 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/bots/BotsResource.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/bots/BotsResource.java @@ -86,6 +86,7 @@ public class BotsResource { @GET @Operation(summary = "List bots", tags = "bots", + description = "Get a list of bots.", responses = { @ApiResponse(responseCode = "200", description = "List of bots", content = @Content(mediaType = "application/json", schema = @Schema(implementation = @@ -100,7 +101,8 @@ public class BotsResource { @GET @Path("/{id}") - @Operation(summary = "Get a bot by ID", tags = "bots", + @Operation(summary = "Get a bot", tags = "bots", + description = "Get a bot by `id`.", responses = { @ApiResponse(responseCode = "200", description = "The bot", content = @Content(mediaType = "application/json", schema = @Schema(implementation = @@ -115,6 +117,7 @@ public class BotsResource { @POST @Operation(summary = "Create a bot", tags = "bots", + description = "Create a new bot.", responses = { @ApiResponse(responseCode = "200", description = "The bot ", content = @Content(mediaType = "application/json", schema = @Schema(implementation = diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/config/ConfigResource.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/config/ConfigResource.java index b8d13284cd4..6416ce02b3c 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/config/ConfigResource.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/config/ConfigResource.java @@ -18,8 +18,13 @@ package org.openmetadata.catalog.resources.config; import io.swagger.annotations.Api; import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.responses.ApiResponse; import org.openmetadata.catalog.CatalogApplicationConfig; +import org.openmetadata.catalog.resources.Collection; import org.openmetadata.catalog.security.AuthenticationConfiguration; +import org.openmetadata.catalog.type.CollectionDescriptor; import javax.ws.rs.GET; import javax.ws.rs.Path; @@ -32,6 +37,7 @@ import javax.ws.rs.core.UriInfo; @Path("/v1/config") @Api(value = "Get configuration") @Produces(MediaType.APPLICATION_JSON) +@Collection(name = "config") public class ConfigResource { private final CatalogApplicationConfig catalogApplicationConfig; @@ -42,7 +48,12 @@ public class ConfigResource { @GET @Path(("/auth")) - @Operation(summary = "Get auth configuration") + @Operation(summary = "Get auth configuration", tags = "general", + responses = { + @ApiResponse(responseCode = "200", description = "Auth configuration", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = AuthenticationConfiguration.class))) + }) public AuthenticationConfiguration getAuthConfig(@Context UriInfo uriInfo, @Context SecurityContext securityContext) { AuthenticationConfiguration authenticationConfiguration = new AuthenticationConfiguration(); if (catalogApplicationConfig.getAuthenticationConfiguration() != null) { diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/dashboards/DashboardResource.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/dashboards/DashboardResource.java index 6905227728d..de9ee26d2e0 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/dashboards/DashboardResource.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/dashboards/DashboardResource.java @@ -97,6 +97,7 @@ public class DashboardResource { .split(",")); @GET @Operation(summary = "List dashboards", tags = "dashboards", + description = "Get a list of dashboards. Use `fields` parameter to get only necessary fields.", responses = { @ApiResponse(responseCode = "200", description = "List of dashboards", content = @Content(mediaType = "application/json", @@ -106,17 +107,15 @@ public class DashboardResource { @Context SecurityContext securityContext, @Parameter(description = "Fields requested in the returned resource", schema = @Schema(type = "string", example = FIELDS)) - @QueryParam("fields") String fieldsParam, - @Parameter(description = "Get dashboards that match fullyQualifiedName", - schema = @Schema(type = "string", example = "snowflakeWestCoast.finances")) - @QueryParam("fqn") String fqn) throws IOException { + @QueryParam("fields") String fieldsParam) throws IOException { Fields fields = new Fields(FIELD_LIST, fieldsParam); - return new DashboardList(addHref(uriInfo, dao.list(fields, fqn))); + return new DashboardList(addHref(uriInfo, dao.list(fields))); } @GET @Path("/{id}") @Operation(summary = "Get a dashboard", tags = "dashboards", + description = "Get a dashboard by `id`.", responses = { @ApiResponse(responseCode = "200", description = "The dashboard", content = @Content(mediaType = "application/json", @@ -135,6 +134,7 @@ public class DashboardResource { @POST @Operation(summary = "Create a dashboard", tags = "dashboards", + description = "Create a new dashboard.", responses = { @ApiResponse(responseCode = "200", description = "The dashboard", content = @Content(mediaType = "application/json", @@ -151,6 +151,7 @@ public class DashboardResource { @PUT @Operation(summary = "Create or update a dashboard", tags = "dashboards", + description = "Create a new dashboard, if it does not exist or update an existing dashboard.", responses = { @ApiResponse(responseCode = "200", description = "The dashboard", content = @Content(mediaType = "application/json", diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/databases/DatabaseResource.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/databases/DatabaseResource.java index e2ce3053127..6426d060b35 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/databases/DatabaseResource.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/databases/DatabaseResource.java @@ -126,6 +126,9 @@ public class DatabaseResource { @GET @Valid @Operation(summary = "List databases", tags = "databases", + description = "Get a list of databases, optionally filtered by `service` it belongs to. Use `fields` " + + "parameter to get only necessary fields. Use cursor-based pagination to limit the number " + + "entries in the list using `limit` and `before` or `after` query params.", responses = { @ApiResponse(responseCode = "200", description = "List of databases", content = @Content(mediaType = "application/json", @@ -183,6 +186,7 @@ public class DatabaseResource { @GET @Path("/{id}") @Operation(summary = "Get a database", tags = "databases", + description = "Get a database by `id`.", responses = { @ApiResponse(responseCode = "200", description = "The database", content = @Content(mediaType = "application/json", @@ -202,7 +206,8 @@ public class DatabaseResource { @GET @Path("/name/{fqn}") - @Operation(summary = "Get a database by fully qualified name", tags = "databases", + @Operation(summary = "Get a database by name", tags = "databases", + description = "Get a database by fully qualified name.", responses = { @ApiResponse(responseCode = "200", description = "The database", content = @Content(mediaType = "application/json", @@ -222,6 +227,7 @@ public class DatabaseResource { @POST @Operation(summary = "Create a database", tags = "databases", + description = "Create a database under an existing `service`.", responses = { @ApiResponse(responseCode = "200", description = "The database", content = @Content(mediaType = "application/json", @@ -240,6 +246,7 @@ public class DatabaseResource { @PATCH @Path("/{id}") @Operation(summary = "Update a database", tags = "databases", + description = "Update an existing database using JsonPatch.", externalDocs = @ExternalDocumentation(description = "JsonPatch RFC", url = "https://tools.ietf.org/html/rfc6902")) @Consumes(MediaType.APPLICATION_JSON_PATCH_JSON) @@ -261,6 +268,7 @@ public class DatabaseResource { @PUT @Operation(summary = "Create or update database", tags = "databases", + description = "Create a database, it it does not exist or update an existing database.", responses = { @ApiResponse(responseCode = "200", description = "The updated database ", content = @Content(mediaType = "application/json", @@ -280,6 +288,7 @@ public class DatabaseResource { @DELETE @Path("/{id}") @Operation(summary = "Delete a database", tags = "databases", + description = "Delete a database by `id`. Database can only be deleted if it has no tables.", responses = { @ApiResponse(responseCode = "200", description = "OK"), @ApiResponse(responseCode = "404", description = "Database for instance {id} is not found") diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/databases/TableResource.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/databases/TableResource.java index 7892e0e56ad..7694fc9a5ad 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/databases/TableResource.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/databases/TableResource.java @@ -121,6 +121,9 @@ public class TableResource { @GET @Operation(summary = "List tables", tags = "tables", + description = "Get a list of tables, optionally filtered by `database` it belongs to. Use `fields` " + + "parameter to get only necessary fields. Use cursor-based pagination to limit the number " + + "entries in the list using `limit` and `before` or `after` query params.", responses = {@ApiResponse(responseCode = "200", description = "List of tables", content = @Content(mediaType = "application/json", schema = @Schema(implementation = TableList.class))) @@ -139,7 +142,7 @@ public class TableResource { @Min(1) @Max(1000000) @QueryParam("limit") int limitParam, - @Parameter(description = "Returns list of tables before this curor", + @Parameter(description = "Returns list of tables before this cursor", schema = @Schema(type = "string")) @QueryParam("before") String before, @Parameter(description = "Returns list of tables after this curor", @@ -176,6 +179,7 @@ public class TableResource { @GET @Path("/{id}") @Operation(summary = "Get a table", tags = "tables", + description = "Get a table by `id`", responses = { @ApiResponse(responseCode = "200", description = "table", content = @Content(mediaType = "application/json", @@ -195,7 +199,8 @@ public class TableResource { @GET @Path("/name/{fqn}") - @Operation(summary = "Get a table by fully qualified name", tags = "tables", + @Operation(summary = "Get a table by name", tags = "tables", + description = "Get a table by fully qualified table name.", responses = { @ApiResponse(responseCode = "200", description = "table", content = @Content(mediaType = "application/json", @@ -216,6 +221,7 @@ public class TableResource { @POST @Operation(summary = "Create a table", tags = "tables", + description = "Create a new table under an existing `database`.", responses = { @ApiResponse(responseCode = "200", description = "table", content = @Content(mediaType = "application/json", @@ -236,6 +242,7 @@ public class TableResource { @PUT @Operation(summary = "Create or update a table", tags = "tables", + description = "Create a table, if it does not exist. If a table already exists, update the table.", responses = { @ApiResponse(responseCode = "200", description = "The table", content = @Content(mediaType = "application/json", @@ -258,6 +265,7 @@ public class TableResource { @PATCH @Path("/{id}") @Operation(summary = "Update a table", tags = "tables", + description = "Update an existing table using JsonPatch.", externalDocs = @ExternalDocumentation(description = "JsonPatch RFC", url = "https://tools.ietf.org/html/rfc6902")) @Consumes(MediaType.APPLICATION_JSON_PATCH_JSON) @@ -282,6 +290,7 @@ public class TableResource { @DELETE @Path("/{id}") @Operation(summary = "Delete a table", tags = "tables", + description = "Delete a table by `id`. Table is not immediately deleted and is only marked as deleted.", responses = { @ApiResponse(responseCode = "200", description = "OK"), @ApiResponse(responseCode = "404", description = "Table for instance {id} is not found") @@ -298,6 +307,7 @@ public class TableResource { @PUT @Path("/{id}/followers") @Operation(summary = "Add a follower", tags = "tables", + description = "Add a user identified by `userId` as followed of this table", responses = { @ApiResponse(responseCode = "200", description = "OK"), @ApiResponse(responseCode = "404", description = "Table for instance {id} is not found") @@ -317,7 +327,8 @@ public class TableResource { @PUT @Path("/{id}/joins") @Operation(summary = "Add table join information", - description = "Join information can only be added for last 30 days starting today", tags = "tables", + description = "Add information about other tables that this table is joined with. Join information can only" + + " be added for the last 30 days starting today.", tags = "tables", responses = { @ApiResponse(responseCode = "200", description = "OK"), @ApiResponse(responseCode = "404", description = "Table for instance {id} is not found"), @@ -335,7 +346,8 @@ public class TableResource { @PUT @Path("/{id}/sampleData") - @Operation(summary = "Add sample data", tags = "tables") + @Operation(summary = "Add sample data", tags = "tables", + description = "Add sample data to the table." ) public Response addSampleData(@Context UriInfo uriInfo, @Context SecurityContext securityContext, @Parameter(description = "Id of the table", schema = @Schema(type = "string")) @@ -347,7 +359,8 @@ public class TableResource { @DELETE @Path("/{id}/followers/{userId}") - @Operation(summary = "Remove a follower", tags = "tables") + @Operation(summary = "Remove a follower", tags = "tables", + description = "Remove the user identified `userId` as a follower of the table.") public Response deleteFollower(@Context UriInfo uriInfo, @Context SecurityContext securityContext, @Parameter(description = "Id of the table", diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/feeds/FeedResource.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/feeds/FeedResource.java index 9b93b9f4709..24419aa12a2 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/feeds/FeedResource.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/feeds/FeedResource.java @@ -89,6 +89,7 @@ public class FeedResource { @GET @Operation(summary = "List threads", tags = "feeds", + description = "Get a list of threads, optionally filtered by `entityLink`.", responses = { @ApiResponse(responseCode = "200", description = "List of threads", content = @Content(mediaType = "application/json", @@ -104,6 +105,7 @@ public class FeedResource { @GET @Path("/{id}") @Operation(summary = "Get a thread", tags = "feeds", + description = "Get a thread by `id`.", responses = { @ApiResponse(responseCode = "200", description = "The thread", content = @Content(mediaType = "application/json", @@ -116,6 +118,7 @@ public class FeedResource { @POST @Operation(summary = "Create a thread", tags = "feeds", + description = "Create a new thread. A thread is created about a data asset when a user posts the first post.", responses = { @ApiResponse(responseCode = "200", description = "The thread", content = @Content(mediaType = "application/json", @@ -135,6 +138,7 @@ public class FeedResource { @POST @Path("/{id}/posts") @Operation(summary = "Add post to a thread", tags = "feeds", + description = "Add a post to an existing thread.", responses = { @ApiResponse(responseCode = "200", description = "The post", content = @Content(mediaType = "application/json", @@ -146,5 +150,4 @@ public class FeedResource { Thread thread = addHref(uriInfo, dao.addPostToThread(id, post)); return Response.created(thread.getHref()).entity(thread).build(); } -} - +} \ No newline at end of file diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/metrics/MetricsResource.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/metrics/MetricsResource.java index 242fe9615ad..4dd3b8896c2 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/metrics/MetricsResource.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/metrics/MetricsResource.java @@ -93,6 +93,7 @@ public class MetricsResource { @GET @Operation(summary = "List metrics", tags = "metrics", + description = "Get a list of metrics. Use `fields` parameter to get only necessary fields.", responses = { @ApiResponse(responseCode = "200", description = "List of metrics", content = @Content(mediaType = "application/json", @@ -101,17 +102,15 @@ public class MetricsResource { public MetricsList list(@Context UriInfo uriInfo, @Parameter(description = "Fields requested in the returned resource", schema = @Schema(type = "string", example = FIELDS)) - @QueryParam("fields") String fieldsParam, - @Parameter(description = "Get metrics that match fullyQualifiedName", - schema = @Schema(type = "string", example = "snowflakeWestCoast.finances")) - @QueryParam("fqn") String fqn) throws IOException { + @QueryParam("fields") String fieldsParam) throws IOException { Fields fields = new Fields(FIELD_LIST, fieldsParam); - return new MetricsList(addHref(uriInfo, dao.list(fields, fqn))); + return new MetricsList(addHref(uriInfo, dao.list(fields))); } @GET @Path("/{id}") @Operation(summary = "Get a metric", tags = "metrics", + description = "Get a metric by `id`.", responses = { @ApiResponse(responseCode = "200", description = "The metrics", content = @Content(mediaType = "application/json", @@ -129,6 +128,7 @@ public class MetricsResource { @POST @Operation(summary = "Create a metric", tags = "metrics", + description = "Create a new metric.", responses = { @ApiResponse(responseCode = "200", description = "The metric", content = @Content(mediaType = "application/json", @@ -143,6 +143,7 @@ public class MetricsResource { @PUT @Operation(summary = "Create or update a metric", tags = "metrics", + description = "Create a new metric, if it does not exist or update an existing metric.", responses = { @ApiResponse(responseCode = "200", description = "The metric", content = @Content(mediaType = "application/json", diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/pipelines/PipelineResource.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/pipelines/PipelineResource.java index 98cde697959..17916a9e346 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/pipelines/PipelineResource.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/pipelines/PipelineResource.java @@ -84,6 +84,7 @@ public class PipelineResource { @GET @Operation(summary = "List pipelines", tags = "pipelines", + description = "Get a list of pipelines.", responses = { @ApiResponse(responseCode = "200", description = "List of pipelines", content = @Content(mediaType = "application/json", @@ -96,6 +97,7 @@ public class PipelineResource { @GET @Path("/{id}") @Operation(summary = "Get a pipeline", tags = "pipelines", + description = "Get a pipeline by `id`.", responses = { @ApiResponse(responseCode = "200", description = "The pipeline", content = @Content(mediaType = "application/json", @@ -108,6 +110,7 @@ public class PipelineResource { @POST @Operation(summary = "Create a pipeline", tags = "pipelines", + description = "Create a new pipeline.", responses = { @ApiResponse(responseCode = "200", description = "The pipeline", content = @Content(mediaType = "application/json", diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/reports/ReportResource.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/reports/ReportResource.java index 06d97e4caac..4e5cbdc9082 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/reports/ReportResource.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/reports/ReportResource.java @@ -93,6 +93,7 @@ public class ReportResource { @GET @Operation(summary = "List reports", tags = "reports", + description = "Get a list of reports. Use `fields` parameter to get only necessary fields.", responses = { @ApiResponse(responseCode = "200", description = "List of reports", content = @Content(mediaType = "application/json", @@ -101,17 +102,15 @@ public class ReportResource { public ReportList list(@Context UriInfo uriInfo, @Parameter(description = "Fields requested in the returned resource", schema = @Schema(type = "string", example = FIELDS)) - @QueryParam("fields") String fieldsParam, - @Parameter(description = "Get report that match fullyQualifiedName", - schema = @Schema(type = "string", example = "snowflakeWestCoast.finances")) - @QueryParam("fqn") String fqn) throws IOException { + @QueryParam("fields") String fieldsParam) throws IOException { Fields fields = new Fields(FIELD_LIST, fieldsParam); - return new ReportList(addHref(uriInfo, dao.list(fields, fqn))); + return new ReportList(addHref(uriInfo, dao.list(fields))); } @GET @Path("/{id}") @Operation(summary = "Get a report", tags = "reports", + description = "Get a report by `id`.", responses = { @ApiResponse(responseCode = "200", description = "The report", content = @Content(mediaType = "application/json", @@ -128,6 +127,7 @@ public class ReportResource { @POST @Operation(summary = "Create a report", tags = "reports", + description = "Create a new report.", responses = { @ApiResponse(responseCode = "200", description = "The report", content = @Content(mediaType = "application/json", @@ -142,6 +142,7 @@ public class ReportResource { @PUT @Operation(summary = "Create or update a report", tags = "reports", + description = "Create a new report, it it does not exist or update an existing report.", responses = { @ApiResponse(responseCode = "200", description = "The report", content = @Content(mediaType = "application/json", diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/search/SearchResource.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/search/SearchResource.java index 2e91d26feb2..3b31dd3a955 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/search/SearchResource.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/search/SearchResource.java @@ -73,7 +73,9 @@ public class SearchResource { @GET @Path("/query") - @Operation(summary = "Search Entities", tags = "search", + @Operation(summary = "Search entities", tags = "search", + description = "Search entities using query test. Use query params `from` and `size` for pagination. Use " + + "`sort_field` to sort the results in `sort_order`.", responses = { @ApiResponse(responseCode = "200", description = "search response", content = @Content(mediaType = "application/json", @@ -86,7 +88,7 @@ public class SearchResource { "1. For listing all tables pass q=*
" + "2. For search tables pass q=*search_term*
" + "3. For searching field names such as search by column_name " + - "pass q=column_naemes:address
" + + "pass q=column_names:address
" + "4. For searching by tag names pass q=tags:user.email
" + "5. When user selects a filter pass q=query_text AND tags:user.email " + "AND platform:MYSQL
" + @@ -148,7 +150,8 @@ public class SearchResource { @GET @Path("/suggest") - @Operation(summary = "Suggest Entities", tags = "search", + @Operation(summary = "Suggest entities", tags = "search", + description = "Get suggested entities used for auto-completion.", responses = { @ApiResponse(responseCode = "200", description = "Table Suggestion API", diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/services/ServiceResource.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/services/ServiceResource.java index 7503cc2724f..f9f0f2b1afa 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/services/ServiceResource.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/services/ServiceResource.java @@ -53,6 +53,7 @@ public class ServiceResource { @GET @Operation(summary = "List service collections", tags = "services", + description = "Get a list of resources under service collection.", responses = { @ApiResponse(responseCode = "200", description = "List of serviceCollections", content = @Content(mediaType = "application/json", diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/services/database/DatabaseServiceResource.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/services/database/DatabaseServiceResource.java index f9d520c3f4b..ef7486b4b66 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/services/database/DatabaseServiceResource.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/services/database/DatabaseServiceResource.java @@ -94,6 +94,7 @@ public class DatabaseServiceResource { @GET @Operation(summary = "List database services", tags = "services", + description = "Get a list of database services.", responses = { @ApiResponse(responseCode = "200", description = "List of database service instances", content = @Content(mediaType = "application/json", @@ -105,7 +106,8 @@ public class DatabaseServiceResource { @GET @Path("/{id}") - @Operation(summary = "Get database service", tags = "services", + @Operation(summary = "Get a database service", tags = "services", + description = "Get a database service by `id`.", responses = { @ApiResponse(responseCode = "200", description = "Database service instance", content = @Content(mediaType = "application/json", @@ -121,6 +123,7 @@ public class DatabaseServiceResource { @GET @Path("/name/{name}") @Operation(summary = "Get database service by name", tags = "services", + description = "Get a database service by the service `name`.", responses = { @ApiResponse(responseCode = "200", description = "Database service instance", content = @Content(mediaType = "application/json", @@ -135,6 +138,7 @@ public class DatabaseServiceResource { @POST @Operation(summary = "Create database service", tags = "services", + description = "Create a new database service.", responses = { @ApiResponse(responseCode = "200", description = "Database service instance", content = @Content(mediaType = "application/json", @@ -156,7 +160,8 @@ public class DatabaseServiceResource { @PUT @Path("/{id}") - @Operation(summary = "Update database service", tags = "services", + @Operation(summary = "Update a database service", tags = "services", + description = "Update an existing database service identified by `id`.", responses = { @ApiResponse(responseCode = "200", description = "Database service instance", content = @Content(mediaType = "application/json", @@ -176,7 +181,9 @@ public class DatabaseServiceResource { @DELETE @Path("/{id}") - @Operation(summary = "Delete database service", tags = "services", + @Operation(summary = "Delete a database service", tags = "services", + description = "Delete a database services. If databases (and tables) belong the service, it can't be " + + "deleted.", responses = { @ApiResponse(responseCode = "200", description = "OK"), @ApiResponse(responseCode = "404", description = "DatabaseService service for instance {id} " + diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/tags/TagResource.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/tags/TagResource.java index 3a5b4d5ffb6..609108572bf 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/tags/TagResource.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/tags/TagResource.java @@ -27,6 +27,7 @@ import io.swagger.v3.oas.annotations.responses.ApiResponse; import org.apache.maven.shared.utils.io.IOUtil; import org.openmetadata.catalog.jdbi3.TagRepository; import org.openmetadata.catalog.resources.Collection; +import org.openmetadata.catalog.security.CatalogAuthorizer; import org.openmetadata.catalog.security.SecurityUtil; import org.openmetadata.catalog.type.CreateTag; import org.openmetadata.catalog.type.CreateTagCategory; @@ -36,7 +37,6 @@ import org.openmetadata.catalog.util.EntityUtil.Fields; import org.openmetadata.catalog.util.JsonUtils; import org.openmetadata.catalog.util.RestUtil; import org.openmetadata.catalog.util.ResultList; -import org.openmetadata.catalog.security.CatalogAuthorizer; import org.openmetadata.common.utils.CommonUtil; import org.slf4j.Logger; import org.slf4j.LoggerFactory; @@ -117,6 +117,7 @@ public class TagResource { @GET @Operation(summary = "List tag categories", tags = "tags", + description = "Get a list of tag categories.", responses = { @ApiResponse(responseCode = "200", description = "The user ", content = @Content(mediaType = "application/json", schema = @Schema(implementation = @@ -136,6 +137,8 @@ public class TagResource { @GET @Path("{category}") @Operation(summary = "Get a tag category", tags = "tags", + description = "Get a tag category identified by name. The response includes tag category information along " + + "with the entire hierarchy of all the children tags.", responses = { @ApiResponse(responseCode = "200", description = "The user ", content = @Content(mediaType = "application/json", schema = @Schema(implementation = @@ -156,6 +159,8 @@ public class TagResource { @GET @Operation(summary = "Get a primary tag", tags = "tags", + description = "Get a primary tag identified by name. The response includes with the entire hierarchy of all" + + " the children tags.", responses = { @ApiResponse(responseCode = "200", description = "The user ", content = @Content(mediaType = "application/json", schema = @Schema(implementation = @@ -187,6 +192,7 @@ public class TagResource { @GET @Path("{category}/{primaryTag}/{secondaryTag}") @Operation(summary = "Get a secondary tag", tags = "tags", + description = "Get a secondary tag identified by name.", responses = { @ApiResponse(responseCode = "200", description = "The user ", content = @Content(mediaType = "application/json", schema = @Schema(implementation = @@ -221,6 +227,8 @@ public class TagResource { @POST @Operation(summary = "Create a tag category", tags = "tags", + description = "Create a new tag category. The request can include the children tags to be created along " + + "with the tag category.", responses = { @ApiResponse(responseCode = "200", description = "The user ", content = @Content(mediaType = "application/json", schema = @Schema(implementation = @@ -240,6 +248,7 @@ public class TagResource { @POST @Path("{category}") @Operation(summary = "Create a primary tag", tags = "tags", + description = "Create a primary tag in the given tag category.", responses = { @ApiResponse(responseCode = "200", description = "The user ", content = @Content(mediaType = "application/json", schema = @Schema(implementation = @@ -263,6 +272,7 @@ public class TagResource { @POST @Path("{category}/{primaryTag}") @Operation(summary = "Create a secondary tag", tags = "tags", + description = "Create a secondary tag under the given primary tag.", responses = { @ApiResponse(responseCode = "200", description = "The user ", content = @Content(mediaType = "application/json", schema = @Schema(implementation = @@ -291,7 +301,8 @@ public class TagResource { @PUT @Path("{category}") - @Operation(summary = "Update an existing tag category", tags = "tags") + @Operation(summary = "Update a tag category", tags = "tags", + description = "Update an existing category identify by category name") public Response updateCategory(@Context UriInfo uriInfo, @Context SecurityContext securityContext, @Parameter(description = "Tag category name", @@ -308,7 +319,8 @@ public class TagResource { @PUT @Path("{category}/{primaryTag}") - @Operation(summary = "Update an existing primaryTag", tags = "tags") + @Operation(summary = "Update a primaryTag", tags = "tags", + description = "Update an existing primaryTag identify by name") public Response updatePrimaryTag(@Context UriInfo uriInfo, @Context SecurityContext securityContext, @Parameter(description = "Tag category name", @@ -330,7 +342,8 @@ public class TagResource { @PUT @Path("{category}/{primaryTag}/{secondaryTag}") - @Operation(summary = "Update an existing primaryTag", tags = "tags") + @Operation(summary = "Update a secondaryTag", tags = "tags", + description = "Update an existing secondaryTag identify by name") public Response updateSecondaryTag(@Context UriInfo uriInfo, @Context SecurityContext securityContext, @Parameter(description = "Tag category name", diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/teams/TeamResource.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/teams/TeamResource.java index 9a50c2af622..a203c61aff1 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/teams/TeamResource.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/teams/TeamResource.java @@ -113,6 +113,9 @@ public class TeamResource { @GET @Valid @Operation(summary = "List teams", tags = "teams", + description = "Get a list of teams. Use `fields` " + + "parameter to get only necessary fields. Use cursor-based pagination to limit the number " + + "entries in the list using `limit` and `before` or `after` query params.", responses = { @ApiResponse(responseCode = "200", description = "List of teams", content = @Content(mediaType = "application/json", @@ -167,6 +170,7 @@ public class TeamResource { @Valid @Path("/{id}") @Operation(summary = "Get a team", tags = "teams", + description = "Get a team by `id`.", responses = { @ApiResponse(responseCode = "200", description = "The team", content = @Content(mediaType = "application/json", @@ -187,6 +191,7 @@ public class TeamResource { @Valid @Path("/name/{name}") @Operation(summary = "Get a team by name", tags = "teams", + description = "Get a team by `name`.", responses = { @ApiResponse(responseCode = "200", description = "The team", content = @Content(mediaType = "application/json", @@ -205,6 +210,7 @@ public class TeamResource { @POST @Operation(summary = "Create a team", tags = "teams", + description = "Create a new team.", responses = { @ApiResponse(responseCode = "200", description = "The team", content = @Content(mediaType = "application/json", @@ -226,6 +232,7 @@ public class TeamResource { @Path("/{id}") @Consumes(MediaType.APPLICATION_JSON_PATCH_JSON) @Operation(summary = "Update a team", tags = "teams", + description = "Update an existing team with JsonPatch.", externalDocs = @ExternalDocumentation(description = "JsonPatch RFC", url = "https://tools.ietf.org/html/rfc6902")) public Team patch(@Context UriInfo uriInfo, @@ -246,6 +253,7 @@ public class TeamResource { @DELETE @Path("/{id}") @Operation(summary = "Delete a team", tags = "teams", + description = "Delete a team by given `id`.", responses = { @ApiResponse(responseCode = "200", description = "OK"), @ApiResponse(responseCode = "404", description = "Team for instance {id} is not found") diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/teams/UserResource.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/teams/UserResource.java index 6cfe1d3ebba..934b2e5c2b3 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/teams/UserResource.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/teams/UserResource.java @@ -116,6 +116,9 @@ public class UserResource { @GET @Valid @Operation(summary = "List users", tags = "users", + description = "Get a list of users. Use `fields` " + + "parameter to get only necessary fields. Use cursor-based pagination to limit the number " + + "entries in the list using `limit` and `before` or `after` query params.", responses = { @ApiResponse(responseCode = "200", description = "The user ", content = @Content(mediaType = "application/json", @@ -170,6 +173,7 @@ public class UserResource { @Valid @Path("/{id}") @Operation(summary = "Get a user", tags = "users", + description = "Get a user by `id`", responses = { @ApiResponse(responseCode = "200", description = "The user", content = @Content(mediaType = "application/json", @@ -189,6 +193,7 @@ public class UserResource { @Valid @Path("/name/{name}") @Operation(summary = "Get a user by name", tags = "users", + description = "Get a user by `name`.", responses = { @ApiResponse(responseCode = "200", description = "The user", content = @Content(mediaType = "application/json", @@ -209,6 +214,7 @@ public class UserResource { @Valid @Path("/loggedInUser") @Operation(summary = "Get current logged in user", tags = "users", + description = "Get the user who is authenticated and is currently logged in.", responses = { @ApiResponse(responseCode = "200", description = "The user", content = @Content(mediaType = "application/json", @@ -227,6 +233,7 @@ public class UserResource { @POST @Operation(summary = "Create a user", tags = "users", + description = "Create a new user.", responses = { @ApiResponse(responseCode = "200", description = "The user ", content = @Content(mediaType = "application/json", @@ -250,6 +257,7 @@ public class UserResource { @Path("/{id}") @Consumes(MediaType.APPLICATION_JSON_PATCH_JSON) @Operation(summary = "Update a user", tags = "users", + description = "Update an existing user using JsonPatch.", externalDocs = @ExternalDocumentation(description = "JsonPatch RFC", url = "https://tools.ietf.org/html/rfc6902")) public User patch(@Context UriInfo uriInfo, @Context SecurityContext securityContext, @PathParam("id") String id, @@ -269,8 +277,8 @@ public class UserResource { @DELETE @Path("/{id}") @Operation(summary = "Deactivate a user", tags = "users", - description = "Users can't be deleted but are deactiveated. The name and display name is changed to include" + - " string `deactivated`.", + description = "Users can't be deleted but are deactivated. The name and display name is prefixed with " + + "the string `deactivated`.", responses = { @ApiResponse(responseCode = "200", description = "OK"), @ApiResponse(responseCode = "404", description = "User for instance {id} is not found") diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/usage/UsageResource.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/usage/UsageResource.java index bd6da5b9df1..f2c57cecef1 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/usage/UsageResource.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/usage/UsageResource.java @@ -70,7 +70,8 @@ public class UsageResource { @GET @Valid @Path("/{entity}/{id}") - @Operation(summary = "Get usage of an entity", tags = "usage", + @Operation(summary = "Get usage", tags = "usage", + description = "Get usage details for an entity identified by `id`.", responses = { @ApiResponse(responseCode = "200", description = "Entity usage", content = @Content(mediaType = "application/json", @@ -103,7 +104,8 @@ public class UsageResource { @GET @Valid @Path("/{entity}/name/{fqn}") - @Operation(summary = "Get usage of an entity by name", tags = "usage", + @Operation(summary = "Get usage by name", tags = "usage", + description = "Get usage details for an entity identified by fully qualified name.", responses = { @ApiResponse(responseCode = "200", description = "Entity usage", content = @Content(mediaType = "application/json", @@ -136,7 +138,9 @@ public class UsageResource { @POST @Path("/{entity}/{id}") - @Operation(summary = "Report usage information for an entity", tags = "usage", + @Operation(summary = "Report usage", tags = "usage", + description = "Report usage information for an entity on a given date. System stores last 30 days of usage " + + "information. Usage information older than 30 days is deleted.", responses = { @ApiResponse(responseCode = "200", description = "Usage information", content = @Content(mediaType = "application/json", @@ -162,7 +166,9 @@ public class UsageResource { @POST @Path("/{entity}/name/{fqn}") - @Operation(summary = "Post usage information for an entity by name", tags = "usage", + @Operation(summary = "Report usage by name", tags = "usage", + description = "Report usage information for an entity by name on a given date. System stores last 30 days " + + "of usage information. Usage information older than 30 days is deleted.", responses = { @ApiResponse(responseCode = "200", description = "Usage information", content = @Content(mediaType = "application/json", @@ -187,7 +193,8 @@ public class UsageResource { @POST @Path("/compute.percentile/{entity}/{date}") - @Operation(summary = "Compute percentiles for an entity on a given day", tags = "usage", + @Operation(summary = "Compute percentiles", tags = "usage", + description = "Compute percentile ranking for an entity based on last 30 days of usage.", responses = { @ApiResponse(responseCode = "201", description = "Percentiles computed"), @ApiResponse(responseCode = "400", description = "Bad request") @@ -199,9 +206,8 @@ public class UsageResource { @PathParam("entity") String entity, @Parameter(description = "ISO 8601 format date to compute percentile on", schema = @Schema(type = "string", example = "2021-01-28")) - @PathParam("date") String date, - @Parameter(description = "Usage information a given date") - @Valid DailyCount usage) { + @PathParam("date") String date) { + // TODO delete this? dao.computePercentile(entity, date); return Response.status(Response.Status.CREATED).build(); } diff --git a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/version/VersionResource.java b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/version/VersionResource.java index 20fe210f9f1..6cb6d59e29c 100644 --- a/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/version/VersionResource.java +++ b/catalog-rest-service/src/main/java/org/openmetadata/catalog/resources/version/VersionResource.java @@ -16,11 +16,11 @@ package org.openmetadata.catalog.resources.version; +import io.swagger.annotations.Api; +import io.swagger.v3.oas.annotations.Operation; import org.openmetadata.catalog.CatalogApplication; import org.openmetadata.catalog.api.CatalogVersion; import org.openmetadata.catalog.resources.Collection; -import io.swagger.annotations.Api; -import io.swagger.v3.oas.annotations.Operation; import org.slf4j.Logger; import org.slf4j.LoggerFactory; @@ -59,7 +59,8 @@ public class VersionResource { public VersionResource() {} @GET - @Operation(summary = "Get version of metadata service", tags = "") + @Operation(summary = "Get version of metadata service", tags = "general", + description = "Get the build version of OpenMetadata service and build timestamp.") public CatalogVersion getCatalogVersion() { return CATALOG_VERSION; } diff --git a/catalog-rest-service/src/main/resources/json/schema/entity/data/table.json b/catalog-rest-service/src/main/resources/json/schema/entity/data/table.json index 7592a4e3cd7..d00b5ef8622 100644 --- a/catalog-rest-service/src/main/resources/json/schema/entity/data/table.json +++ b/catalog-rest-service/src/main/resources/json/schema/entity/data/table.json @@ -223,6 +223,7 @@ "description": "Information on other tables that this table column is frequently joined with", "properties": { "columns": { + "description": "List of local column names (not fully qualified column names) of the table", "type": "array", "items": { "$ref": "#/definitions/columnName" @@ -232,7 +233,7 @@ "description": "Data for a multiple rows of the table", "type": "array", "items": { - "description": "Data for a single row of the table", + "description": "Data for a single row of the table with in the same order as columns fields", "type": "array" } } diff --git a/docs/openmetadata-apis/apis.md b/docs/openmetadata-apis/apis.md index 53e408baae1..c9ced31329e 100644 --- a/docs/openmetadata-apis/apis.md +++ b/docs/openmetadata-apis/apis.md @@ -1,7 +1,8 @@ -# APIs +# Overview +OpenMetadata supports REST APIs for getting metadata in and out of metadata store. The API resources are grouped under following categories: +- **Data assets** - includes resources for data entities, such as `databases`, `tables`, and `topics`. Resources for data assets created from data, such as `dashboards`, `reports`, `metrics`, and `ML Features` are part of this collection. `pipelines`, `notebooks`, etc. that are used for creating data assets are also available as resources as of this collection. +- **Teams and Users** - includes `users`, `teams`, a special type of user called `bots` that performs many automated tasks such as ingestion. +- **Services** - are services that OpenMetadata integrates with. Currently `databaseService` is the only service under this collection that represents data sources. In the future, services related to Dashboards, Reports, ETL pipelines will be added under this collection. +- **Glossary** - OpenMetadata supports hierarchical tags that can be used to build business vocabulary to describe and classify data available under `tags` resource. -OpenMetadata supports REST APIs for getting data in and out of metadata system. APIs are built using current best practices of REST API design. - -TODO add links to the various parts of the document -[Click here](http://localhost:8585/api/swagger) for Swagger API Documentation