CLOUDP-155918: basic migration guide and docs structure (#9)

.github/workflows/autoupdate-prod.yaml

@@ -26,6 +26,10 @@ jobs:
         if: steps.verify-changed-files.outputs.files_changed == 'true'
         working-directory: ./tools
         run: make clean_and_generate
+      - name: Run generation
+        if: steps.verify-changed-files.outputs.files_changed == 'true'
+        working-directory: ./tools
+        run: make generate_docs
       - uses: peter-evans/create-pull-request@v5
         if: steps.verify-changed-files.outputs.files_changed == 'true'
         with:

.gitignore

@@ -39,3 +39,6 @@ node_modules
 example_cluster_aws
 admin/api
 admin/.openapi-generator
+scripts/gh-md-toc
+docs/.openapi-generator/*
+

Makefile

@@ -58,3 +58,7 @@ openapi-pipeline:
 	echo "Validating generated SDK"
 	go test go.mongodb.org/atlas-sdk/test
 
+.PHONY: generate-docs
+generate-docs:
+	$(MAKE) -C tools generate_docs
+	./scripts/toc.sh

README.md

@@ -9,7 +9,7 @@ A Go SDK for the [MongoDB Atlas API](https://docs.atlas.mongodb.com/api/).
 
 Note that `atlas-sdk-go` only supports the two most recent major versions of Go.
 
-## Usage
+## Getting started
 
 ### Adding Dependency
 
@@ -42,6 +42,10 @@ The services of a client divide the API into logical chunks and correspond to
 the structure of the Atlas API documentation at
 https://www.mongodb.com/docs/atlas/reference/api-resources-spec/.
 
+## Documentation
+
+Please refer to the [docs](./docs)
+
 ## Examples
 
 Example for creating an dedicated MongoDB cluster on AWS infrastructure
@@ -50,64 +54,6 @@ Example for creating an dedicated MongoDB cluster on AWS infrastructure
 go run ./examples/example_cluster_aws.go
 ```
 
-## Authentication
-
-The `atlas-sdk-go` library uses Digest authentication. 
-To obtain authentication tokens users can use Atlas UI or Atlas CLI 
-For more information please follow: https://www.mongodb.com/docs/atlas/api/api-authentication,
-
-## Error Handling
-
-SDK enables users to obtain detailed information about errors returned from backend.
-Errors are represented by [ErrorObject](./admin/model_error.go).
-Users should rely on the error code for detection of specific error cases.
-
-### Fetching Error Object
-```go
-import errors "go.mongodb.org/atlas-sdk/admin"
-
-projects, response, err := sdk.ProjectsApi.ListProjects(ctx).Execute()
-apiError := errors.AsError(err)
-fmt.Println(apiError)
-```
-
-### Checking for existence of specific error code
-```go
-import errors "go.mongodb.org/atlas-sdk/admin"
-
-
-if errors.IsErrorCode(err, "code"){
- // Do something
-}
-```
-
-## Advanced usage
-
-###  Fluent and Struct Based API
-
-Generated client support two different ways to execute API requests.
-1. Fluent API: where users are supplying arguments using chain of functions (default)
-2. Struct API: Suppling request data using an single go structure containing request body and arguments
-
-#### Fluent API example
-
-Fluent API should be used by default to handle all requests.
-
-```go
-    projects, response, err := sdk.ProjectsApi.ListProjects(ctx).
-	    ItemsPerPage(1).Execute()
-```  
-
-#### Struct based API example
-
-Struct based API is particularly useful for HTTP GET requests where we need to pass number of arguments to the function without checking 
-```go
-	listParams := &mongodbatlas.ListProjectsApiParams{ItemsPerPage: mongodbatlas.PtrInt32(1)}
-	projects, response, err := sdk.ProjectsApi.ListProjectsWithParams(ctx, listParams).Execute()
-```    
-
-> NOTE: Struct based API is an still experimental feature.
-
 ## Contributing
 
 See our [CONTRIBUTING.md](CONTRIBUTING.md) Guide.

docs/README.md

@@ -0,0 +1,28 @@
+# Atlas SDK GO documentation
+
+* [Atlas Go API client](./docs/doc_1_reference.md#atlas-go-api-client)
+   * [Documentation for API Endpoints](./docs/doc_1_reference.md#documentation-for-api-endpoints)
+   * [Documentation For Models](./docs/doc_1_reference.md#documentation-for-models)
+
+* [Error Handling](./docs/doc_2_error_handling.md#error-handling)
+   * [Fetching Error Object](./docs/doc_2_error_handling.md#fetching-error-object)
+   * [Checking for existence of specific error code](./docs/doc_2_error_handling.md#checking-for-existence-of-specific-error-code)
+
+* [Migration Guide](./docs/doc_3_migration.md#migration-guide)
+   * [Summary](./docs/doc_3_migration.md#summary)
+   * [Background](./docs/doc_3_migration.md#background)
+   * [Structural changes](./docs/doc_3_migration.md#structural-changes)
+      * [Client Initialization](./docs/doc_3_migration.md#client-initialization)
+      * [Error handling](./docs/doc_3_migration.md#error-handling)
+      * [Format of the API interface](./docs/doc_3_migration.md#format-of-the-api-interface)
+      * [Different naming conventions for SDK methods](./docs/doc_3_migration.md#different-naming-conventions-for-sdk-methods)
+      * [Multiple choices when creating request body objects](./docs/doc_3_migration.md#multiple-choices-when-creating-request-body-objects)
+
+* [Authentication](./docs/doc_4_authentication.md#authentication)
+
+* [Advanced usage](./docs/doc_5_advanced_usage.md#advanced-usage)
+   * [Fluent and Struct Based API](./docs/doc_5_advanced_usage.md#fluent-and-struct-based-api)
+      * [Fluent API example](./docs/doc_5_advanced_usage.md#fluent-api-example)
+      * [Struct based API example](./docs/doc_5_advanced_usage.md#struct-based-api-example)
+
+<!-- Created by https://github.com/ekalinin/github-markdown-toc -->

docs/doc_2_error_handling.md

@@ -0,0 +1,26 @@
+
+# Error Handling
+
+SDK enables users to obtain detailed information about errors returned from backend.
+Errors are represented by [ErrorObject](./admin/model_error.go).
+Users should rely on the error code for detection of specific error cases.
+
+## Fetching Error Object
+```go
+import "go.mongodb.org/atlas-sdk/admin"
+
+projects, response, err := admin.ProjectsApi.ListProjects(ctx).Execute()
+apiError := admin.AsError(err)
+fmt.Println(apiError)
+```
+
+## Checking for existence of specific error code
+```go
+import admin "go.mongodb.org/atlas-sdk/admin"
+
+projects, response, err := admin.ProjectsApi.ListProjects(ctx).Execute()
+if admin.IsErrorCode(err, "code"){
+ // Do something
+}
+```
+

docs/doc_3_migration.md

@@ -0,0 +1,87 @@
+# Migration Guide
+
+This document is meant to help you migrate from [go-client-mongodb-atlas](https://github.com/mongodb/go-client-mongodb-atlas) to [mongodb/atlas-sdk-go](https://github.com/mongodb/atlas-sdk-go).
+
+## Summary
+
+End users can migrate from [mongodb/go-client-mongodb-atlas](https://github.com/mongodb/go-client-mongodb-atlas) to [mongodb/atlas-sdk-go](https://github.com/mongodb/atlas-sdk-go) partially
+by using both librarires at the same time. 
+
+An [go-client-mongodb-atlas](https://github.com/mongodb/go-client-mongodb-atlas) will no longer receive major feature updates.
+We strongly recommend updating to [mongodb/atlas-sdk-go](https://github.com/mongodb/atlas-sdk-go) for the latest changes.
+
+## Background
+
+[mongodb/atlas-sdk-go](https://github.com/mongodb/atlas-sdk-go) is based on Atlas V2 API. 
+Atlas-sdk-go hides a complexity related to Versioned API by exposing versioned API as golang methods.
+End users need to be aware that major sdk releases can introduce breaking changes only in the small subset of the Atlas APIs.
+
+## Structural changes
+
+SDK have been rewriten completely from scratch. 
+Our team made attempts to minimize amount of changes required for the end users. 
+brings a number of changes in how API requests are made. 
+
+### Client Initialization
+
+New SDK has different methods for the initialization of the clients. 
+
+```go
+import admin "go.mongodb.org/atlas-sdk/admin" 
+sdk, err := admin.NewClient(
+    // Authentication using ApiKey and ApiSecret
+    admin.UseDigestAuth(apiKey, apiSecret))
+```
+
+> NOTE: Both SDKs use Digest based authentication. The same credentials will apply. 
+
+Please follow [authentication guide](https://github.com/mongodb/atlas-sdk-go#authentication) for more information.
+
+### Error handling 
+
+Error handling requires developers to use dedicated methods for casting errors to APIError objects.
+
+```go
+    apiErr, _ := admin.AsError(err)
+    log.Fatalf("Error when performing SDK request: %v", apiErr.GetDetail())
+```
+Please follow [error handling guide](https://github.com/mongodb/atlas-sdk-go#error-handling) for more information.
+
+### Format of the API interface
+
+API interface has changed to differentiate APIs from other methods in the SDK.  
+Each API method has an Api suffix. For example:
+
+`sdk.Projects` will now `sdk.ProjectsApi`
+
+Each method now explains the object that is created. For example:
+
+`sdk.Projects.create()` will become `sdk.ProjectsApi.createProject(...)`
+
+Please refer to the [endpoint documentation](https://github.com/mongodb/go-client-mongodb-atlas/tree/main/mongodbatlasv2#documentation-for-api-endpoints) for more information.
+
+### Different naming conventions for SDK methods
+
+Model names and properties are formatted in PascalCase format for clarity and predictability of the methods and field names. 
+For example, _ClusterAWSProviderSettings_ will become now _ClusterAwsProviderSettings_.  
+
+The same applies to property names:
+
+For example, `ID` fields will become `Id` etc. 
+
+### Multiple choices when creating request body objects
+
+New SDK improves clarity for request and response objects. For situations when the endpoint accepts multiple formats of the payload (polymorphism), users are able to specify instances of the Api models they want to use for a particular request. For example, when creating a cluster we can use one of the dedicated RegionConfigs objects (AWSRegionConfig, GCPRegionConfig, etc.): 
+
+
+```go
+//...
+RegionConfig{
+ 	// Dedicated region config for AWS cloud
+    AWSRegionConfig: &mongodbatlas.AWSRegionConfig{
+        //AWS-specific fields are here
+        RegionName:   &regionName, 
+    },
+}
+//...
+```

docs/doc_4_authentication.md

@@ -0,0 +1,7 @@
+# Authentication
+
+The `atlas-sdk-go` library uses Digest authentication. 
+To obtain authentication tokens users can use Atlas UI or Atlas CLI 
+
+For more information please follow: https://www.mongodb.com/docs/atlas/api/api-authentication
+

docs/doc_5_advanced_usage.md

@@ -0,0 +1,26 @@
+# Advanced usage
+
+##  Fluent and Struct Based API
+
+Generated client support two different ways to execute API requests.
+1. Fluent API: where users are supplying arguments using chain of functions (default)
+2. Struct API: Suppling request data using an single go structure containing request body and arguments
+
+### Fluent API example
+
+Fluent API should be used by default to handle all requests.
+
+```go
+    projects, response, err := sdk.ProjectsApi.ListProjects(ctx).
+	    ItemsPerPage(1).Execute()
+```  
+
+### Struct based API example
+
+Struct based API is particularly useful for HTTP GET requests where we need to pass number of arguments to the function without checking 
+```go
+	listParams := &mongodbatlas.ListProjectsApiParams{ItemsPerPage: mongodbatlas.PtrInt32(1)}
+	projects, response, err := sdk.ProjectsApi.ListProjectsWithParams(ctx, listParams).Execute()
+```    
+
+> NOTE: Struct based API is an still experimental feature.