diff --git a/.github/workflows/autoupdate-prod.yaml b/.github/workflows/autoupdate-prod.yaml index 156ad501..1420ae93 100644 --- a/.github/workflows/autoupdate-prod.yaml +++ b/.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: diff --git a/.gitignore b/.gitignore index 0db6e983..b9af0100 100644 --- a/.gitignore +++ b/.gitignore @@ -39,3 +39,6 @@ node_modules example_cluster_aws admin/api admin/.openapi-generator +scripts/gh-md-toc +docs/.openapi-generator/* + diff --git a/Makefile b/Makefile index 86212820..bb6f9c14 100644 --- a/Makefile +++ b/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 diff --git a/README.md b/README.md index cfe33cec..fba7439f 100644 --- a/README.md +++ b/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. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..ea0cfea8 --- /dev/null +++ b/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) + + diff --git a/admin/README.md b/docs/doc_1_reference.md similarity index 100% rename from admin/README.md rename to docs/doc_1_reference.md diff --git a/docs/doc_2_error_handling.md b/docs/doc_2_error_handling.md new file mode 100644 index 00000000..0aea4639 --- /dev/null +++ b/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 +} +``` + diff --git a/docs/doc_3_migration.md b/docs/doc_3_migration.md new file mode 100644 index 00000000..7b32f959 --- /dev/null +++ b/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: ®ionName, + }, +} +//... +``` diff --git a/docs/doc_4_authentication.md b/docs/doc_4_authentication.md new file mode 100644 index 00000000..08412e9b --- /dev/null +++ b/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 + diff --git a/docs/doc_5_advanced_usage.md b/docs/doc_5_advanced_usage.md new file mode 100644 index 00000000..6574fc22 --- /dev/null +++ b/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. diff --git a/docs/docs/AccessTrackingApi.md b/docs/docs/AccessTrackingApi.md new file mode 100644 index 00000000..7552c813 --- /dev/null +++ b/docs/docs/AccessTrackingApi.md @@ -0,0 +1,184 @@ +# \AccessTrackingApi + +All URIs are relative to *https://cloud.mongodb.com* + +Method | HTTP request | Description +------------- | ------------- | ------------- +[**ListAccessLogsByClusterName**](AccessTrackingApi.md#ListAccessLogsByClusterName) | **Get** /api/atlas/v2/groups/{groupId}/dbAccessHistory/clusters/{clusterName} | Return Database Access History for One Cluster using Its Cluster Name +[**ListAccessLogsByHostname**](AccessTrackingApi.md#ListAccessLogsByHostname) | **Get** /api/atlas/v2/groups/{groupId}/dbAccessHistory/processes/{hostname} | Return Database Access History for One Cluster using Its Hostname + + + +## ListAccessLogsByClusterName + +> MongoDBAccessLogsList ListAccessLogsByClusterName(ctx, groupId, clusterName).AuthResult(authResult).End(end).IpAddress(ipAddress).NLogs(nLogs).Start(start).Execute() + +Return Database Access History for One Cluster using Its Cluster Name + + + +### Example + +```go +package main + +import ( + "context" + "fmt" + "os" + + "go.mongodb.org/atlas-sdk/admin" +) + +func main() { + apiKey := os.Getenv("MDB_API_KEY") + apiSecret := os.Getenv("MDB_API_SECRET") + + sdk := admin.NewClient(admin.UseDigestAuth(apiKey, apiSecret)) + + groupId := "32b6e34b3d91647abb20e7b8" // string | + clusterName := "clusterName_example" // string | + authResult := true // bool | (optional) + end := "end_example" // string | (optional) + ipAddress := "ipAddress_example" // string | (optional) + nLogs := int64(789) // int64 | (optional) (default to 20000) + start := time.Now() // time.Time | (optional) + + resp, r, err := sdk.AccessTrackingApi.ListAccessLogsByClusterName(context.Background(), groupId, clusterName).AuthResult(authResult).End(end).IpAddress(ipAddress).NLogs(nLogs).Start(start).Execute() + if err != nil { + fmt.Fprintf(os.Stderr, "Error when calling `AccessTrackingApi.ListAccessLogsByClusterName``: %v\n", err) + apiError := admin.AsError(err) + fmt.Fprintf(os.Stderr, "Error obj: %v\n", apiError) + } + // response from `ListAccessLogsByClusterName`: MongoDBAccessLogsList + fmt.Fprintf(os.Stdout, "Response from `AccessTrackingApi.ListAccessLogsByClusterName`: %v\n", resp) +} +``` + +### Path Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- +**ctx** | **context.Context** | context for authentication, logging, cancellation, deadlines, tracing, etc. +**groupId** | **string** | Unique 24-hexadecimal digit string that identifies your project. Use the [/groups](#tag/Projects/operation/listProjects) endpoint to retrieve all projects to which the authenticated user has access. **NOTE**: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups. | +**clusterName** | **string** | Human-readable label that identifies the cluster. | + +### Other Parameters + +Other parameters are passed through a pointer to a apiListAccessLogsByClusterNameRequest struct via the builder pattern + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + + + **authResult** | **bool** | Flag that indicates whether the response returns the successful authentication attempts only. | + **end** | **string** | Date and time when to stop retrieving database history. If you specify **end**, you must also specify **start**. This parameter uses the ISO 8601 timestamp format in UTC. | + **ipAddress** | **string** | One Internet Protocol address that attempted to authenticate with the database. | + **nLogs** | **int64** | Maximum number of lines from the log to return. | [default to 20000] + **start** | **time.Time** | Date and time when MongoDB Cloud begins retrieving database history. If you specify **start**, you must also specify **end**. This parameter uses the ISO 8601 timestamp format in UTC. | + +### Return type + +[**MongoDBAccessLogsList**](MongoDBAccessLogsList.md) + +### Authorization +[DigestAuth](../../README.md) + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: application/vnd.atlas.2023-01-01+json, application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) +[[Back to Model list]](../README.md#documentation-for-models) +[[Back to README]](../README.md) + + +## ListAccessLogsByHostname + +> MongoDBAccessLogsList ListAccessLogsByHostname(ctx, groupId, hostname).AuthResult(authResult).End(end).IpAddress(ipAddress).NLogs(nLogs).Start(start).Execute() + +Return Database Access History for One Cluster using Its Hostname + + + +### Example + +```go +package main + +import ( + "context" + "fmt" + "os" + + "go.mongodb.org/atlas-sdk/admin" +) + +func main() { + apiKey := os.Getenv("MDB_API_KEY") + apiSecret := os.Getenv("MDB_API_SECRET") + + sdk := admin.NewClient(admin.UseDigestAuth(apiKey, apiSecret)) + + groupId := "32b6e34b3d91647abb20e7b8" // string | + hostname := "hostname_example" // string | + authResult := true // bool | (optional) + end := time.Now() // time.Time | (optional) + ipAddress := "ipAddress_example" // string | (optional) + nLogs := int(56) // int | (optional) (default to 20000) + start := time.Now() // time.Time | (optional) + + resp, r, err := sdk.AccessTrackingApi.ListAccessLogsByHostname(context.Background(), groupId, hostname).AuthResult(authResult).End(end).IpAddress(ipAddress).NLogs(nLogs).Start(start).Execute() + if err != nil { + fmt.Fprintf(os.Stderr, "Error when calling `AccessTrackingApi.ListAccessLogsByHostname``: %v\n", err) + apiError := admin.AsError(err) + fmt.Fprintf(os.Stderr, "Error obj: %v\n", apiError) + } + // response from `ListAccessLogsByHostname`: MongoDBAccessLogsList + fmt.Fprintf(os.Stdout, "Response from `AccessTrackingApi.ListAccessLogsByHostname`: %v\n", resp) +} +``` + +### Path Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- +**ctx** | **context.Context** | context for authentication, logging, cancellation, deadlines, tracing, etc. +**groupId** | **string** | Unique 24-hexadecimal digit string that identifies your project. Use the [/groups](#tag/Projects/operation/listProjects) endpoint to retrieve all projects to which the authenticated user has access. **NOTE**: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups. | +**hostname** | **string** | Fully qualified domain name or IP address of the MongoDB host that stores the log files that you want to download. | + +### Other Parameters + +Other parameters are passed through a pointer to a apiListAccessLogsByHostnameRequest struct via the builder pattern + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + + + **authResult** | **bool** | Flag that indicates whether the response returns the successful authentication attempts only. | + **end** | **time.Time** | Date and time when to stop retrieving database history. If you specify **end**, you must also specify **start**. This parameter uses the ISO 8601 timestamp format in UTC. | + **ipAddress** | **string** | One Internet Protocol address that attempted to authenticate with the database. | + **nLogs** | **int** | Maximum number of lines from the log to return. | [default to 20000] + **start** | **time.Time** | Date and time when MongoDB Cloud begins retrieving database history. If you specify **start**, you must also specify **end**. This parameter uses the ISO 8601 timestamp format in UTC. | + +### Return type + +[**MongoDBAccessLogsList**](MongoDBAccessLogsList.md) + +### Authorization +[DigestAuth](../../README.md) + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: application/vnd.atlas.2023-01-01+json, application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) +[[Back to Model list]](../README.md#documentation-for-models) +[[Back to README]](../README.md) + diff --git a/scripts/toc.sh b/scripts/toc.sh new file mode 100755 index 00000000..e3cb6b16 --- /dev/null +++ b/scripts/toc.sh @@ -0,0 +1,14 @@ +#!/usr/bin/env bash +set -o errexit +set -o nounset + +if which "./scripts/gh-md-toc" >/dev/null 2>&1; then + echo "Binary gh-md-toc exists." +else + wget https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc + chmod a+x gh-md-toc +fi + +echo "generating table of contents" +echo "# Atlas SDK GO documentation" > ./docs/README.md +./scripts/gh-md-toc --skip-header ./docs/doc_*.md >> ./docs/README.md diff --git a/tools/Makefile b/tools/Makefile index 77c1e09a..36085d36 100644 --- a/tools/Makefile +++ b/tools/Makefile @@ -1,5 +1,6 @@ export OPENAPI_FOLDER=../openapi export SDK_FOLDER=../admin +export DOC_FOLDER=../docs .DEFAULT_GOAL := generate_client @@ -21,3 +22,8 @@ generate_client: .PHONY: clean_and_generate clean_and_generate: clean_client generate_client + +.PHONY: generate_docs +generate_docs: + ./scripts/generate_docs.sh + diff --git a/tools/config/.go-ignore b/tools/config/.go-ignore index a077ec9c..1fc33b5f 100644 --- a/tools/config/.go-ignore +++ b/tools/config/.go-ignore @@ -13,3 +13,4 @@ **openapi-generator-ignore **travis.yml **git_push.sh +**/README.md diff --git a/tools/config/.go-ignore-docs b/tools/config/.go-ignore-docs new file mode 100644 index 00000000..6270b153 --- /dev/null +++ b/tools/config/.go-ignore-docs @@ -0,0 +1,9 @@ +# OpenAPI Generator Ignore +# Generated by openapi-generator https://github.com/openapitools/openapi-generator + +# Use this file to prevent files from being overwritten by the generator. +# The patterns follow closely to .gitignore or .dockerignore. + +**/*.* +!**/*.md +.openapi-generator diff --git a/tools/config/go-templates/api_doc.mustache b/tools/config/go-templates/api_doc.mustache index 623a15be..1858c6fc 100644 --- a/tools/config/go-templates/api_doc.mustache +++ b/tools/config/go-templates/api_doc.mustache @@ -1,4 +1,4 @@ -# {{invokerPackage}}\{{classname}}{{#description}} +{{!X-GEN-CUSTOM}}# {{invokerPackage}}\{{classname}}{{#description}} {{.}}{{/description}} @@ -29,23 +29,25 @@ import ( "context" "fmt" "os" -{{#vendorExtensions.x-go-import}} -{{{vendorExtensions.x-go-import}}} -{{/vendorExtensions.x-go-import}} - {{goImportAlias}} "{{gitHost}}/{{gitUserId}}/{{gitRepoId}}{{#isGoSubmodule}}/{{packageName}}{{/isGoSubmodule}}" + + "go.mongodb.org/atlas-sdk/admin" ) func main() { + apiKey := os.Getenv("MDB_API_KEY") + apiSecret := os.Getenv("MDB_API_SECRET") + + sdk := admin.NewClient(admin.UseDigestAuth(apiKey, apiSecret)) + {{#allParams}} - {{paramName}} := {{{vendorExtensions.x-go-example}}} // {{{dataType}}} | {{{description}}}{{^required}} (optional){{/required}}{{#defaultValue}} (default to {{{.}}}){{/defaultValue}} + {{paramName}} := {{{vendorExtensions.x-go-example}}} // {{{dataType}}} | {{^required}} (optional){{/required}}{{#defaultValue}} (default to {{{.}}}){{/defaultValue}} {{/allParams}} - configuration := {{goImportAlias}}.NewConfiguration() - apiClient := {{goImportAlias}}.NewAPIClient(configuration) - {{#returnType}}resp, {{/returnType}}r, err := apiClient.{{classname}}.{{operationId}}(context.Background(){{#pathParams}}, {{paramName}}{{/pathParams}}){{#allParams}}{{^isPathParam}}.{{vendorExtensions.x-export-param-name}}({{paramName}}){{/isPathParam}}{{/allParams}}.Execute() + {{#returnType}}resp, {{/returnType}}r, err := sdk.{{classname}}.{{operationId}}(context.Background(){{#pathParams}}, {{paramName}}{{/pathParams}}){{#allParams}}{{^isPathParam}}.{{vendorExtensions.x-export-param-name}}({{paramName}}){{/isPathParam}}{{/allParams}}.Execute() if err != nil { fmt.Fprintf(os.Stderr, "Error when calling `{{classname}}.{{operationId}}``: %v\n", err) - fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r) + apiError := admin.AsError(err) + fmt.Fprintf(os.Stderr, "Error obj: %v\n", apiError) } {{#returnType}} // response from `{{operationId}}`: {{{.}}} @@ -76,8 +78,8 @@ Name | Type | Description | Notes {{#returnType}}{{#returnTypeIsPrimitive}}**{{{returnType}}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}[**{{{returnType}}}**]({{returnBaseType}}.md){{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}} (empty response body){{/returnType}} ### Authorization - -{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{{name}}}](../README.md#{{{name}}}){{^-last}}, {{/-last}}{{/authMethods}} +{{!X-GEN-CUSTOM}} +[DigestAuth](../../README.md) ### HTTP request headers diff --git a/tools/scripts/generate.sh b/tools/scripts/generate.sh index db327028..301652d8 100755 --- a/tools/scripts/generate.sh +++ b/tools/scripts/generate.sh @@ -33,7 +33,7 @@ echo "# Running Client Generation" npm exec openapi-generator-cli -- generate \ -c "./config/config.yaml" -i "$openapiFileLocation" -o "$SDK_FOLDER" \ --package-name="$client_package" \ - --type-mappings=integer=int\ + --type-mappings=integer=int \ --ignore-file-override=config/.go-ignore gofmt -s -w "$SDK_FOLDER/"*.go diff --git a/tools/scripts/generate_docs.sh b/tools/scripts/generate_docs.sh new file mode 100755 index 00000000..2aafe521 --- /dev/null +++ b/tools/scripts/generate_docs.sh @@ -0,0 +1,29 @@ +#!/usr/bin/env bash +set -o errexit +set -o nounset + +###################################################### +# Generate client using OpenAPI generator +# Environment variables: +# OPENAPI_FOLDER - folder containing openapi file +# OPENAPI_FILE_NAME - openapi file name +# SDK_FOLDER - folder location for generated client +###################################################### + +OPENAPI_FOLDER=${OPENAPI_FOLDER:-./openapi} +OPENAPI_FILE_NAME=${OPENAPI_FILE_NAME:-atlas-api.yaml} +DOC_FOLDER=${DOC_FOLDER:-./docs} + +transformed_file="atlas-api-transformed.yaml" +client_package="admin" +openapiFileLocation="$OPENAPI_FOLDER/$transformed_file" + +echo "# Running Client Generation" + +npm exec openapi-generator-cli -- generate \ + -c "./config/config.yaml" -i "$openapiFileLocation" -o "$DOC_FOLDER" \ + --package-name="$client_package" \ + --type-mappings=integer=int \ + --ignore-file-override=config/.go-ignore-docs + +mv "$DOC_FOLDER"/README.md "$DOC_FOLDER"/doc_1_reference.md