Skip to content
Merged
Show file tree
Hide file tree
Changes from 12 commits
Commits
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
9 changes: 9 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -188,6 +188,15 @@ Before adding a command please make sure that your api exists in the GO SDK.
> [!TIP]
> Atlas CLI provides an experimental generator, make sure to try it out in [tools/cli-generator](./tools/cli-generator)

### Making changes to API Generator

API generator is a tool that generates code based on Atlas OpenAPI specification.
It is used to generate `./internal/api/commands.go` file that contains all API commands.

If you are making changes to the generator please make sure to run `make gen-api-commands` to update the generated code.

Please also run `UPDATE_SNAPSHOTS=true go test ./...` from the `tools/cmd/api-generator` directory to update the snapshots. When you run the command for the first time it will fail, showing the diff. Upon running the command again the test will pass as the snapshots have been updated.

### API Interactions

Atlas CLI use [atlas-sdk-go](https://github.com/mongodb/atlas-sdk-go) for all backend integration.
Expand Down
2,210 changes: 1,326 additions & 884 deletions internal/api/commands.go

Large diffs are not rendered by default.

15 changes: 13 additions & 2 deletions internal/cli/api/api.go
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,17 @@ func createAPICommandGroupToCobraCommand(group shared_api.Group) *cobra.Command
func convertAPIToCobraCommand(command shared_api.Command) (*cobra.Command, error) {
// command properties
commandName := strcase.ToLowerCamel(command.OperationID)
commandOperationID := command.OperationID
commandAliases := command.Aliases

if command.ShortOperationID != "" {
// Add original operation ID to aliases
commandAliases = append(commandAliases, commandName)
// Use shortOperationID
commandName = strcase.ToLowerCamel(command.ShortOperationID)
commandOperationID = command.ShortOperationID
}

shortDescription, longDescription := splitShortAndLongDescription(command.Description)

// flag values
Expand All @@ -114,11 +125,11 @@ func convertAPIToCobraCommand(command shared_api.Command) (*cobra.Command, error

cmd := &cobra.Command{
Use: commandName,
Aliases: command.Aliases,
Aliases: commandAliases,
Short: shortDescription,
Long: longDescription,
Annotations: map[string]string{
"operationId": command.OperationID,
"operationId": commandOperationID,
},
PreRunE: func(cmd *cobra.Command, _ []string) error {
// Go through all commands that have not been touched/modified by the user and try to populate them from the users profile
Expand Down
5 changes: 3 additions & 2 deletions tools/cmd/api-generator/commands.go.tmpl
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,9 @@ var Commands = shared_api.GroupedAndSortedCommands{
Commands: []shared_api.Command{
{{- range .Commands }}
{
OperationID: `{{ .OperationID }}`,
Aliases: {{if not .Aliases}} nil {{else}} []string{ {{ range $i, $alias := .Aliases }}{{if $i}},{{end}}`{{ $alias }}`{{end}} } {{end}},
OperationID: `{{ .OperationID }}`,
ShortOperationID: `{{ .ShortOperationID }}`,
Aliases: {{if not .Aliases}} nil {{else}} []string{ {{ range $i, $alias := .Aliases }}{{if $i}},{{end}}`{{ $alias }}`{{end}} } {{end}},
Description: `{{ .Description }}`,
RequestParameters: shared_api.RequestParameters{
URL: `{{ .RequestParameters.URL }}`,
Expand Down
21 changes: 12 additions & 9 deletions tools/cmd/api-generator/convert_commands.go
Original file line number Diff line number Diff line change
Expand Up @@ -101,16 +101,22 @@ func extractSunsetDate(extensions map[string]any) *time.Time {
type operationExtensions struct {
skip bool
operationID string
shortOperationID string
operationAliases []string
}

func extractExtensionsFromOperation(operation *openapi3.Operation) operationExtensions {
ext := operationExtensions{
skip: false,
operationID: operation.OperationID,
shortOperationID: "",
operationAliases: []string{},
}

if shortOperationID, ok := operation.Extensions["x-xgen-operation-id-override"].(string); ok && shortOperationID != "" {
ext.shortOperationID = shortOperationID
}

if extensions, okExtensions := operation.Extensions["x-xgen-atlascli"].(map[string]any); okExtensions && extensions != nil {
if extSkip, okSkip := extensions["skip"].(bool); okSkip && extSkip {
ext.skip = extSkip
Expand All @@ -127,6 +133,7 @@ func extractExtensionsFromOperation(operation *openapi3.Operation) operationExte
if overrides := extractOverrides(operation.Extensions); overrides != nil {
if overriddenOperationID, ok := overrides["operationId"].(string); ok && overriddenOperationID != "" {
ext.operationID = overriddenOperationID
ext.shortOperationID = ""
}
}
}
Expand All @@ -141,6 +148,7 @@ func operationToCommand(now time.Time, path, verb string, operation *openapi3.Op
}

operationID := extensions.operationID
shortOperationID := extensions.shortOperationID
aliases := extensions.operationAliases

httpVerb, err := api.ToHTTPVerb(verb)
Expand All @@ -167,21 +175,16 @@ func operationToCommand(now time.Time, path, verb string, operation *openapi3.Op
return nil, fmt.Errorf("failed to clean description: %w", err)
}

if overrides := extractOverrides(operation.Extensions); overrides != nil {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[q] for my own understanding, we have removed operationId overrides officially in benefit of x-xgen-operation-id-override? I'm trying to understand if we haven't missed any overrides here that should've been translated to x-xgen-operation-id-override

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is no mention of replacing the operationId override officially by x-xgen-operation-id-override in the TD so I think I removed this my mistake. Will add it back in

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but does it make sense to keep two types of overrides? I think my main concern is just making sure we're handling both if they exist, but we could look into how the overrides are being added at the moment and if we should rename them, or maybe, we don't even use them

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since both target the same field (operationID) one will override the other. From what I can see in the latest openapi spec, I don't think operationID override is used. It was appear as x-operationid right?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

interesting! I think this is the AtlasCLI framework for overrides, e.g. search for the openapi spec tests with x-xgen-atlascli. There is a different format there for different overrides. Perharps by keeping this here, the idea is that if we need to override via AtlasCLI we can, let's drop a comment here maybe capturing this behaviour in case we see this in the future?

Copy link
Collaborator Author

@Luke-Sanderson Luke-Sanderson Oct 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh yes this is the x-xgen-atlascli one. I think I might have originally removed it because I thought it was duplicating the logic from here. Yes I agree there is a use case for this override for overriding the operationId only for atlascli and I think that this override should take priority.

I will add a comment to reflect this

if overriddenOperationID, ok := overrides["operationId"].(string); ok && overriddenOperationID != "" {
operationID = overriddenOperationID
}
}

watcher, err := extractWatcherProperties(operation.Extensions)
if err != nil {
return nil, err
}

command := api.Command{
OperationID: operationID,
Aliases: aliases,
Description: description,
OperationID: operationID,
ShortOperationID: shortOperationID,
Aliases: aliases,
Description: description,
RequestParameters: api.RequestParameters{
URL: path,
QueryParameters: parameters.query,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,9 @@ var Commands = shared_api.GroupedAndSortedCommands{
Description: `Returns, adds, edits, and removes database deployments. Changes to cluster configurations can affect costs. This resource requires your Project ID.`,
Commands: []shared_api.Command{
{
OperationID: `createCluster`,
Aliases: nil,
OperationID: `createCluster`,
ShortOperationID: ``,
Aliases: nil,
Description: `Creates one cluster in the specified project. Clusters contain a group of hosts that maintain the same data set. This resource can create clusters with asymmetrically-sized shards. Each project supports up to 25 database deployments. To use this resource, the requesting API Key must have the Project Owner role. This feature is not available for serverless clusters.

This command is autogenerated and corresponds 1:1 with the Atlas API endpoint https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-createcluster.
Expand Down Expand Up @@ -109,8 +110,9 @@ NOTE: Groups and projects are synonymous terms. Your group id is the same as you
},
},
{
OperationID: `listClusters`,
Aliases: nil,
OperationID: `listClusters`,
ShortOperationID: ``,
Aliases: nil,
Description: `Returns the details for all clusters in the specific project to which you have access. Clusters contain a group of hosts that maintain the same data set. The response includes clusters with asymmetrically-sized shards. To use this resource, the requesting API Key must have the Project Read Only role. This feature is not available for serverless clusters.

This command is autogenerated and corresponds 1:1 with the Atlas API endpoint https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-listclusters.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,9 @@ var Commands = shared_api.GroupedAndSortedCommands{
Description: ``,
Commands: []shared_api.Command{
{
OperationID: `createCluster`,
Aliases: nil,
OperationID: `createCluster`,
ShortOperationID: ``,
Aliases: nil,
Description: `Creates one cluster in the specified project. Clusters contain a group of hosts that maintain the same data set. This resource can create clusters with asymmetrically-sized shards. Each project supports up to 25 database deployments. To use this resource, the requesting API Key must have the Project Owner role. This feature is not available for serverless clusters.

This command is autogenerated and corresponds 1:1 with the Atlas API endpoint https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-createcluster.
Expand Down Expand Up @@ -109,8 +110,9 @@ NOTE: Groups and projects are synonymous terms. Your group id is the same as you
},
},
{
OperationID: `listClusters`,
Aliases: nil,
OperationID: `listClusters`,
ShortOperationID: ``,
Aliases: nil,
Description: `Returns the details for all clusters in the specific project to which you have access. Clusters contain a group of hosts that maintain the same data set. The response includes clusters with asymmetrically-sized shards. To use this resource, the requesting API Key must have the Project Read Only role. This feature is not available for serverless clusters.

This command is autogenerated and corresponds 1:1 with the Atlas API endpoint https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-listclusters.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,9 @@ var Commands = shared_api.GroupedAndSortedCommands{
Description: `Returns, adds, edits, and removes database deployments. Changes to cluster configurations can affect costs. This resource requires your Project ID.`,
Commands: []shared_api.Command{
{
OperationID: `createCluster`,
Aliases: nil,
OperationID: `createCluster`,
ShortOperationID: ``,
Aliases: nil,
Description: `Creates one cluster in the specified project. Clusters contain a group of hosts that maintain the same data set. This resource can create clusters with asymmetrically-sized shards. Each project supports up to 25 database deployments. To use this resource, the requesting API Key must have the Project Owner role. This feature is not available for serverless clusters.

This command is autogenerated and corresponds 1:1 with the Atlas API endpoint https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-createcluster.
Expand Down Expand Up @@ -109,8 +110,9 @@ NOTE: Groups and projects are synonymous terms. Your group id is the same as you
},
},
{
OperationID: `listClusters`,
Aliases: nil,
OperationID: `listClusters`,
ShortOperationID: ``,
Aliases: nil,
Description: `Returns the details for all clusters in the specific project to which you have access. Clusters contain a group of hosts that maintain the same data set. The response includes clusters with asymmetrically-sized shards. To use this resource, the requesting API Key must have the Project Read Only role. This feature is not available for serverless clusters.

This command is autogenerated and corresponds 1:1 with the Atlas API endpoint https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-listclusters.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,9 @@ var Commands = shared_api.GroupedAndSortedCommands{
Description: `Returns, adds, edits, and removes database deployments. Changes to cluster configurations can affect costs. This resource requires your Project ID.`,
Commands: []shared_api.Command{
{
OperationID: `getCollStatsLatencyNamespaceClusterMeasurements`,
Aliases: nil,
OperationID: `getCollStatsLatencyNamespaceClusterMeasurements`,
ShortOperationID: ``,
Aliases: nil,
Description: `Get a list of the Coll Stats Latency cluster-level measurements for the given namespace.

This command is autogenerated and corresponds 1:1 with the Atlas API endpoint https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-getcollstatslatencynamespaceclustermeasurements.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,9 @@ var Commands = shared_api.GroupedAndSortedCommands{
Description: `Returns, adds, edits, and removes database deployments. Changes to cluster configurations can affect costs. This resource requires your Project ID.`,
Commands: []shared_api.Command{
{
OperationID: `createClusterX`,
Aliases: nil,
OperationID: `createClusterX`,
ShortOperationID: ``,
Aliases: nil,
Description: `OVERRIDDEN

This command is autogenerated and corresponds 1:1 with the Atlas API endpoint https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-createcluster.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,9 @@ var Commands = shared_api.GroupedAndSortedCommands{
Description: `Returns, adds, edits, and removes database deployments. Changes to cluster configurations can affect costs. This resource requires your Project ID.`,
Commands: []shared_api.Command{
{
OperationID: `createCluster`,
Aliases: nil,
OperationID: `createCluster`,
ShortOperationID: ``,
Aliases: nil,
Description: `Creates one cluster in the specified project. Clusters contain a group of hosts that maintain the same data set. This resource can create clusters with asymmetrically-sized shards. Each project supports up to 25 database deployments. To use this resource, the requesting API Key must have the Project Owner role. This feature is not available for serverless clusters.

This command is autogenerated and corresponds 1:1 with the Atlas API endpoint https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-createcluster.
Expand Down Expand Up @@ -109,8 +110,9 @@ NOTE: Groups and projects are synonymous terms. Your group id is the same as you
},
},
{
OperationID: `listClusters`,
Aliases: nil,
OperationID: `listClusters`,
ShortOperationID: ``,
Aliases: nil,
Description: `Returns the details for all clusters in the specific project to which you have access. Clusters contain a group of hosts that maintain the same data set. The response includes clusters with asymmetrically-sized shards. To use this resource, the requesting API Key must have the Project Read Only role. This feature is not available for serverless clusters.

This command is autogenerated and corresponds 1:1 with the Atlas API endpoint https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-listclusters.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,9 @@ var Commands = shared_api.GroupedAndSortedCommands{
Description: `Returns, adds, edits, and removes database deployments. Changes to cluster configurations can affect costs. This resource requires your Project ID.`,
Commands: []shared_api.Command{
{
OperationID: `createCluster`,
Aliases: []string{`createDatabase`, `createServer`},
OperationID: `createCluster`,
ShortOperationID: ``,
Aliases: []string{`createDatabase`, `createServer`},
Description: `Creates one cluster in the specified project. Clusters contain a group of hosts that maintain the same data set. This resource can create clusters with asymmetrically-sized shards. Each project supports up to 25 database deployments. To use this resource, the requesting API Key must have the Project Owner role. This feature is not available for serverless clusters.

This command is autogenerated and corresponds 1:1 with the Atlas API endpoint https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-createcluster.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,9 @@ var Commands = shared_api.GroupedAndSortedCommands{
Description: `Returns, adds, edits, and removes database deployments. Changes to cluster configurations can affect costs. This resource requires your Project ID.`,
Commands: []shared_api.Command{
{
OperationID: `listClusters`,
Aliases: nil,
OperationID: `listClusters`,
ShortOperationID: ``,
Aliases: nil,
Description: `Returns the details for all clusters in the specific project to which you have access. Clusters contain a group of hosts that maintain the same data set. The response includes clusters with asymmetrically-sized shards. To use this resource, the requesting API Key must have the Project Read Only role. This feature is not available for serverless clusters.

This command is autogenerated and corresponds 1:1 with the Atlas API endpoint https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-listclusters.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,9 @@ var Commands = shared_api.GroupedAndSortedCommands{
Description: `Returns, adds, edits, and removes database deployments. Changes to cluster configurations can affect costs. This resource requires your Project ID.`,
Commands: []shared_api.Command{
{
OperationID: `createCluster`,
Aliases: []string{`createDatabase`, `createServer`},
OperationID: `createCluster`,
ShortOperationID: ``,
Aliases: []string{`createDatabase`, `createServer`},
Description: `Creates one cluster in the specified project. Clusters contain a group of hosts that maintain the same data set. This resource can create clusters with asymmetrically-sized shards. Each project supports up to 25 database deployments. To use this resource, the requesting API Key must have the Project Owner role. This feature is not available for serverless clusters.

This command is autogenerated and corresponds 1:1 with the Atlas API endpoint https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-createcluster.
Expand Down Expand Up @@ -128,8 +129,9 @@ NOTE: Groups and projects are synonymous terms. Your group id is the same as you
},
},
{
OperationID: `getCluster`,
Aliases: nil,
OperationID: `getCluster`,
ShortOperationID: ``,
Aliases: nil,
Description: `Returns the details for one cluster in the specified project. Clusters contain a group of hosts that maintain the same data set. The response includes clusters with asymmetrically-sized shards. To use this resource, the requesting API Key must have the Project Read Only role. This feature is not available for serverless clusters.


Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,9 @@ var Commands = shared_api.GroupedAndSortedCommands{
Description: `Returns, adds, and edits Charts Dashboard instances. This resource applies only to projects with a Charts tenant, and requires your Project ID.`,
Commands: []shared_api.Command{
{
OperationID: `exportChartsDashboard`,
Aliases: nil,
OperationID: `exportChartsDashboard`,
ShortOperationID: ``,
Aliases: nil,
Description: `Exports the specified Charts dashboard. To use this resource, the requesting Service Account or API Key must have the Project Read Only role.

This command is autogenerated and corresponds 1:1 with the Atlas API endpoint https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-exportchartsdashboard.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,9 @@ var Commands = shared_api.GroupedAndSortedCommands{
Description: `Returns, adds, and edits Charts Dashboard instances. This resource applies only to projects with a Charts tenant, and requires your Project ID.`,
Commands: []shared_api.Command{
{
OperationID: `exportChartsDashboard`,
Aliases: nil,
OperationID: `exportChartsDashboard`,
ShortOperationID: ``,
Aliases: nil,
Description: `Exports the specified Charts dashboard. To use this resource, the requesting Service Account or API Key must have the Project Read Only role.

This command is autogenerated and corresponds 1:1 with the Atlas API endpoint https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-exportchartsdashboard.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,9 @@ var Commands = shared_api.GroupedAndSortedCommands{
Description: `Returns, adds, and edits Charts Dashboard instances. This resource applies only to projects with a Charts tenant, and requires your Project ID.`,
Commands: []shared_api.Command{
{
OperationID: `exportChartsDashboard`,
Aliases: nil,
OperationID: `exportChartsDashboard`,
ShortOperationID: ``,
Aliases: nil,
Description: `Exports the specified Charts dashboard. To use this resource, the requesting Service Account or API Key must have the Project Read Only role.

This command is autogenerated and corresponds 1:1 with the Atlas API endpoint https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-exportchartsdashboard.
Expand Down
Loading
Loading