Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve swagger documentation #7734

Merged
merged 3 commits into from
Jun 15, 2023
Merged

Improve swagger documentation #7734

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2e9fe2e
Move to own swagger tag
mandy-chessell Jun 15, 2023
9f4a79a
Improve swagger tags
mandy-chessell Jun 15, 2023
9f57398
Merge branch 'main' of https://github.com/odpi/egeria into code2023
mandy-chessell Jun 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions ...etadata-implementation/platform-services/Egeria-platform-services.postman_collection.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,7 @@
"response": []
},
{
"name": "Get registered governance services",
"name": "Get governance services",
"request": {
"method": "GET",
"header": [],
Expand All @@ -235,7 +235,7 @@
"response": []
},
{
"name": "Get registered common services",
"name": "Get common services",
"request": {
"method": "GET",
"header": [],
Expand All @@ -259,7 +259,7 @@
"response": []
},
{
"name": "Get all registered services",
"name": "Get all services",
"request": {
"method": "GET",
"header": [],
Expand Down Expand Up @@ -624,18 +624,18 @@
"method": "GET",
"header": [],
"url": {
"raw": "{{baseURL}}/open-metadata/platform-services/users/{{user}}/server-platform/connector-types/org.odpi.openmetadata.adapters.connectors.integration.basicfiles.DataFilesMonitorIntegrationProvider",
"raw": "{{baseURL}}/open-metadata/platform-services/users/{{adminUserId}}/server-platform/connector-types/org.odpi.openmetadata.metadatasecurity.samples.CocoPharmaPlatformSecurityProvider",
"host": [
"{{baseURL}}"
],
"path": [
"open-metadata",
"platform-services",
"users",
"{{user}}",
"{{adminUserId}}",
"server-platform",
"connector-types",
"org.odpi.openmetadata.adapters.connectors.integration.basicfiles.DataFilesMonitorIntegrationProvider"
"org.odpi.openmetadata.metadatasecurity.samples.CocoPharmaPlatformSecurityProvider"
]
},
"description": "Retrieve the list of services that have been requested inside of a specific server running on this OMAG Server Platform."
Expand Down
6 changes: 3 additions & 3 deletions ...ava/org/odpi/openmetadata/platformservices/server/spring/OMAGServerOperationResource.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,9 @@

@Tag(name="Platform Services", description="The platform services provides the APIs for querying the Open Metadata and Governance (OMAG) " +
"Server Platform. It is able to start an stop OMAG Servers and discovering information " +
"about the OMAG Servers that it is hosting.",
externalDocs=@ExternalDocumentation(description="Platform Services",url="https://egeria-project.org/services/platform-services/overview"))

"about the OMAG Servers that the OMAG Server Platform is hosting. " +
"It is also able to dynamically change the platform metadata security connector.",
externalDocs=@ExternalDocumentation(description="Further Information", url="https://egeria-project.org/services/platform-services/overview"))

public class OMAGServerOperationResource
{
Expand Down
20 changes: 11 additions & 9 deletions ...rg/odpi/openmetadata/platformservices/server/spring/OMAGServerPlatformActiveResource.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,14 +27,16 @@
* platform and the services that are active within them.
*/

@Tag(name="Platform Services", description="The platform services provides the APIs for querying the Open Metadata and Governance (OMAG) " +
"Server Platform. It is able to start an stop OMAG Servers and discovering information " +
"about the OMAG Servers that it is hosting.",
externalDocs=@ExternalDocumentation(description="Platform Services",url="https://egeria-project.org/services/platform-services/overview"))

@RestController
@RequestMapping("/open-metadata/platform-services/users/{userId}/server-platform")

@Tag(name="Platform Services", description="The platform services provides the APIs for querying the Open Metadata and Governance (OMAG) " +
"Server Platform. It is able to start an stop OMAG Servers and discovering information " +
"about the OMAG Servers that the OMAG Server Platform is hosting. " +
"It is also able to dynamically change the platform metadata security connector.",
externalDocs=@ExternalDocumentation(description="Further Information", url="https://egeria-project.org/services/platform-services/overview"))

public class OMAGServerPlatformActiveResource
{
private final OMAGServerPlatformActiveServices platformAPI = new OMAGServerPlatformActiveServices();
Expand Down Expand Up @@ -153,7 +155,7 @@ public RegisteredOMAGServicesResponse getRegisteredViewServices(@Parameter(descr
* @return list of service descriptions
*/
@GetMapping(path = "/registered-services/governance-services")
@Operation( summary = "getRegisteredGovernanceServices",
@Operation( summary = "getGovernanceServices",
description="Retrieve a list of governance services registered on this platform",
responses = {
@ApiResponse(responseCode = "200", description="list of service descriptions",
Expand All @@ -178,7 +180,7 @@ public RegisteredOMAGServicesResponse getRegisteredGovernanceServices(@Parameter
* @return list of service descriptions
*/
@GetMapping(path = "/registered-services/common-services")
@Operation( summary = "getRegisteredCommonServices",
@Operation( summary = "getCommonServices",
description="Retrieve a list of common services registered on this platform",
responses = {
@ApiResponse(responseCode = "200",description="list of service descriptions",
Expand All @@ -196,14 +198,14 @@ public RegisteredOMAGServicesResponse getRegisteredCommonServices(@Parameter(des


/**
* Return the list of all services that are registered (supported) in this OMAG Server Platform.
* Return the list of all services that are supported in this OMAG Server Platform.
*
* @param userId calling user
* @return list of service descriptions
*/
@GetMapping(path = "/registered-services")
@Operation( summary = "getAllRegisteredServices",
description="Retrieve a list of all services registered on this platform",
@Operation( summary = "getAllServices",
description="Retrieve a list of all services available on this platform",
responses = {
@ApiResponse(responseCode = "200",description="list of service descriptions",
content = @Content(
Expand Down
5 changes: 3 additions & 2 deletions ...rg/odpi/openmetadata/platformservices/server/spring/OMAGServerPlatformOriginResource.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,9 @@

@Tag(name="Platform Services", description="The platform services provides the APIs for querying the Open Metadata and Governance (OMAG) " +
"Server Platform. It is able to start an stop OMAG Servers and discovering information " +
"about the OMAG Servers that it is hosting.",
externalDocs=@ExternalDocumentation(description="Platform Services",url="https://egeria-project.org/services/platform-services/overview"))
"about the OMAG Servers that the OMAG Server Platform is hosting. " +
"It is also able to dynamically change the platform metadata security connector.",
externalDocs=@ExternalDocumentation(description="Further Information", url="https://egeria-project.org/services/platform-services/overview"))

public class OMAGServerPlatformOriginResource
{
Expand Down
21 changes: 11 additions & 10 deletions .../odpi/openmetadata/platformservices/server/spring/OMAGServerPlatformSecurityResource.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,16 +28,17 @@

@Tag(name="Platform Services", description="The platform services provides the APIs for querying the Open Metadata and Governance (OMAG) " +
"Server Platform. It is able to start an stop OMAG Servers and discovering information " +
"about the OMAG Servers that it is hosting.",
externalDocs=@ExternalDocumentation(description="Platform Services",url="https://egeria-project.org/services/platform-services/overview"))
"about the OMAG Servers that the OMAG Server Platform is hosting. " +
"It is also able to dynamically change the platform metadata security connector.",
externalDocs=@ExternalDocumentation(description="Further Information", url="https://egeria-project.org/services/platform-services/overview"))

public class OMAGServerPlatformSecurityResource
{
private final OMAGServerPlatformSecurityServices adminSecurityAPI = new OMAGServerPlatformSecurityServices();


/**
* Set up a platform security connector
* Set up a platform metadata security connector
*
* @param userId calling user.
* @param requestBody requestBody used to create and configure the connector that performs platform security
Expand All @@ -46,9 +47,9 @@ public class OMAGServerPlatformSecurityResource
@PostMapping(path = "/connection")

@Operation(summary="setPlatformSecurityConnection",
description="Set up a platform security connector to control access to the platform and admin services.",
externalDocs=@ExternalDocumentation(description="Metadata Security",
url="https://egeria-project.org/features/metadata-security/overview/"))
description="Set up a platform metadata security connector to control access to the platform and admin services. This overrides the ",
externalDocs=@ExternalDocumentation(description="Further Information",
url="https://egeria-project.org/services/platform-services/overview/#dynamically-configuring-the-platform-metadata-security-connector"))

public VoidResponse setPlatformSecurityConnection(@PathVariable String userId,
@RequestBody PlatformSecurityRequestBody requestBody)
Expand All @@ -58,7 +59,7 @@ public VoidResponse setPlatformSecurityConnection(@PathVariable String


/**
* Return the connection object for platform security connector. Null is returned if no platform security
* Return the connection object for platform metadata security connector. Null is returned if no platform security
* has been set up.
*
* @param userId calling user
Expand All @@ -67,7 +68,7 @@ public VoidResponse setPlatformSecurityConnection(@PathVariable String
@GetMapping(path = "/connection")

@Operation(summary="getPlatformSecurityConnection",
description="Return the connection object for platform security connector. Null is returned if no platform security has been set up.",
description="Return the connection object for platform metadata security connector. Null is returned if no connector has been set up.",
externalDocs=@ExternalDocumentation(description="Metadata Security",
url="https://egeria-project.org/features/metadata-security/overview/"))

Expand All @@ -88,8 +89,8 @@ public ConnectionResponse getPlatformSecurityConnection(@PathVariable String

@Operation(summary="clearPlatformSecurityConnection",
description="Clear the connection object for platform security. This means there is no platform security set up. Note that this command must be issued by a user that has permission to operate the OMAG Server Platform.",
externalDocs=@ExternalDocumentation(description="Metadata Security",
url="https://egeria-project.org/features/metadata-security/overview/"))
externalDocs=@ExternalDocumentation(description="Further Information",
url="https://egeria-project.org/services/platform-services/overview/#dynamically-configuring-the-platform-metadata-security-connector"))

public VoidResponse clearPlatformSecurityConnection(@PathVariable String userId)
{
Expand Down
5 changes: 2 additions & 3 deletions .../org/odpi/openmetadata/platformservices/server/spring/OldOperationalServicesResource.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,9 @@
@RequestMapping("/open-metadata/admin-services/users/{userId}/servers/{serverName}")

@Tag(name="Administration Services - Operational - Deprecated",
description="The operational administration services support the management " +
"of OMAG Server instances. This includes starting and stopping the servers as well as querying and changing their operational state.",
description="Use the Platform Services.",
externalDocs=@ExternalDocumentation(description="Further information",
url="https://egeria-project.org/guides/operations/overview/"))
url="https://egeria-project.org/services/platform-services/overview/"))

@Deprecated
public class OldOperationalServicesResource
Expand Down
5 changes: 2 additions & 3 deletions ...ava/org/odpi/openmetadata/platformservices/server/spring/OldPlatformSecurityResource.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,9 @@
@RestController
@RequestMapping("/open-metadata/admin-services/users/{userId}/platform/security")

@Tag(name="Administration Services - Platform Configuration - Deprecated", description="The platform configuration administration services support the " +
"configuration of the security and configuration store connectors for an OMAG Server Platform.",
@Tag(name="Administration Services - Platform Security Configuration - Deprecated", description="Use the platform services.",
externalDocs=@ExternalDocumentation(description="Further information",
url="https://egeria-project.org/guides/admin/configuring-the-omag-server-platform/"))
url="https://egeria-project.org/services/platform-services/overview/#dynamically-configuring-the-platform-metadata-security-connector"))
@Deprecated
public class OldPlatformSecurityResource
{
Expand Down
5 changes: 2 additions & 3 deletions ...in/java/org/odpi/openmetadata/platformservices/server/spring/OldServerOriginResource.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,9 @@
@RequestMapping("/open-metadata/admin-services/users/{userId}")

@Tag(name="Administration Services - Operational - Deprecated",
description="The operational administration services support the management " +
"of OMAG Server instances. This includes starting and stopping the servers as well as querying and changing their operational state.",
description="Use the Platform Services.",
externalDocs=@ExternalDocumentation(description="Further information",
url="https://egeria-project.org/guides/operations/overview/"))
url="https://egeria-project.org/services/platform-services/overview/"))
@Deprecated
public class OldServerOriginResource
{
Expand Down
8 changes: 3 additions & 5 deletions ...penmetadata/viewservices/serverauthor/server/spring/ConfigAccessServicesViewResource.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,15 +17,13 @@
@RestController
@RequestMapping("/servers/{serverName}/open-metadata/view-services/server-author/users/{userId}/servers/{serverToBeConfiguredName}")

@Tag(name="Administration Services - Server Configuration", description="The server configuration administration services support the configuration" +
" of the open metadata and governance services within an OMAG Server. This configuration determines which of the Open Metadata and " +
"Governance (OMAG) services are active.",
@Tag(name="Server Author OMVS", description="The Server Author OMVS is for user interfaces supporting the creating and editing of OMAG Server Configuration Documents.",
externalDocs=@ExternalDocumentation(description="Further information",
url="https://egeria-project.org/guides/admin/servers/"))
url="https://egeria-project.org/services/omvs/server-author/overview"))

public class ConfigAccessServicesViewResource
{
private ServerAuthorViewRESTServices adminAPI = new ServerAuthorViewRESTServices();
private final ServerAuthorViewRESTServices adminAPI = new ServerAuthorViewRESTServices();



Expand Down
14 changes: 6 additions & 8 deletions ...odpi/openmetadata/viewservices/serverauthor/server/spring/ConfigDefaultsViewResource.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,22 +17,20 @@
@RestController
@RequestMapping("/servers/{serverName}/open-metadata/view-services/server-author/users/{userId}/servers/{serverToBeConfiguredName}")

@Tag(name="Administration Services - Server Configuration", description="The server configuration administration services support the configuration" +
" of the open metadata and governance services within an OMAG Server. This configuration determines which of the Open Metadata and " +
"Governance (OMAG) services are active.",
externalDocs=@ExternalDocumentation(description="Further information",
url="https://egeria-project.org/guides/admin/servers/"))
@Tag(name="Server Author OMVS", description="The Server Author OMVS is for user interfaces supporting the creating and editing of OMAG Server Configuration Documents.",
externalDocs=@ExternalDocumentation(description="Further information",
url="https://egeria-project.org/services/omvs/server-author/overview"))

public class ConfigDefaultsViewResource
{
private ServerAuthorViewRESTServices adminAPI = new ServerAuthorViewRESTServices();
private final ServerAuthorViewRESTServices adminAPI = new ServerAuthorViewRESTServices();

/**
* Set up the default event bus for embedding in event-driven connector. The resulting connector will
* be used for example, in the OMRS Topic Connector for each cohort, the in and out topics for each Access Service and
* possibly the local repository's event mapper.
*
* When the event bus is configured, it is used only on future configuration. It does not effect
* <br><br>
* When the event bus is configured, it is used only on future configuration. It does not affect
* existing configuration.
*
* @param userId user that is issuing the request.
Expand Down
15 changes: 7 additions & 8 deletions ...etadata/viewservices/serverauthor/server/spring/ConfigRepositoryServicesViewResource.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@

import io.swagger.v3.oas.annotations.ExternalDocumentation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.odpi.openmetadata.adminservices.configuration.properties.CohortTopicStructure;
import org.odpi.openmetadata.commonservices.ffdc.rest.FFDCResponseBase;
import org.odpi.openmetadata.commonservices.ffdc.rest.NullRequestBody;
import org.odpi.openmetadata.commonservices.ffdc.rest.VoidResponse;
Expand All @@ -24,13 +23,12 @@
@RestController
@RequestMapping("/servers/{serverName}/open-metadata/view-services/server-author/users/{userId}/servers/{serverToBeConfiguredName}")

@Tag(name = "Administration Services - Server Configuration", description = "The server configuration administration services support the configuration" +
" of the open metadata and governance services within an OMAG Server. This configuration determines which of the Open Metadata and " +
"Governance (OMAG) services are active.",
externalDocs = @ExternalDocumentation(description = "Further information",
url = "https://egeria-project.org/guides/admin/servers/"))
@Tag(name="Server Author OMVS", description="The Server Author OMVS is for user interfaces supporting the creating and editing of OMAG Server Configuration Documents.",
externalDocs=@ExternalDocumentation(description="Further information",
url="https://egeria-project.org/services/omvs/server-author/overview"))

class ConfigRepositoryServicesViewResource {
private ServerAuthorViewRESTServices serverAPI = new ServerAuthorViewRESTServices();
private final ServerAuthorViewRESTServices serverAPI = new ServerAuthorViewRESTServices();

/**
* Set up an in memory local repository. This repository uses hashmaps to store content. It is useful
Expand All @@ -44,6 +42,7 @@ class ConfigRepositoryServicesViewResource {
* OMAGNotAuthorizedException the supplied userId is not authorized to issue this command or
* OMAGInvalidParameterException invalid serverName or localRepositoryMode parameter.
*/
@SuppressWarnings(value = "unused")
@PostMapping(path = "/local-repository/mode/in-memory-repository")
public FFDCResponseBase setInMemLocalRepository(@PathVariable String userId,
@PathVariable String serverName,
Expand Down Expand Up @@ -313,7 +312,7 @@ public FFDCResponseBase deleteAuditLogDestinationSupportedSeverities(@PathVariab

/**
* Enable registration of server to an open metadata repository cohort using the default topic structure (DEDICATED_TOPICS).
*
* <br><br>
* A cohort is a group of open metadata
* repositories that are sharing metadata. An OMAG server can connect to zero, one or more cohorts.
* Each cohort needs a unique name. The members of the cohort use a shared topic to exchange registration
Expand Down
Loading