diff --git a/Makefile b/Makefile index f4cacff8..3c0876ac 100644 --- a/Makefile +++ b/Makefile @@ -266,3 +266,11 @@ shellcheck: .PHONY: setup-new-sdk setup-new-sdk: ./scripts/setup_new_sdk.sh + +.PHONY: build-client-ruby +build-client-ruby: + make build-client sdk_language=ruby tmpdir=${TMP_DIR} + +.PHONY: test-client-ruby +test-client-ruby: build-client-ruby + # to follow... diff --git a/config/clients/ruby/.openapi-generator-ignore b/config/clients/ruby/.openapi-generator-ignore new file mode 100644 index 00000000..3ceb8c5c --- /dev/null +++ b/config/clients/ruby/.openapi-generator-ignore @@ -0,0 +1,19 @@ +Gemfile +.gitignore +.rspec +.rubocop.yml +.travis.yml +.gitlab-ci.yml +git_push.sh +.github/CODEOWNERS +.github/ISSUE_TEMPLATE/bug_report.yaml +.github/ISSUE_TEMPLATE/feature_request.yaml +.github/ISSUE_TEMPLATE/config.yaml +Rakefile +spec/api/* +spec/models/* +spec/api_client_spec.rb +spec/spec_helper.rb +spec/configuration_spec.rb +.codecov.yml + diff --git a/config/clients/ruby/config.overrides.json b/config/clients/ruby/config.overrides.json new file mode 100644 index 00000000..5a999643 --- /dev/null +++ b/config/clients/ruby/config.overrides.json @@ -0,0 +1,38 @@ +{ + "sdkId": "ruby", + "gitRepoId": "ruby-sdk", + "packageName": "openfga", + "packageVersion": "0.1.5", + "packageDescription": "Ruby SDK for OpenFGA", + "packageDetailedDescription": "This is community-driven Ruby SDK for OpenFGA. It provides a wrapper around the [OpenFGA API definition](https://openfga.dev/api).", + "allowUnicodeIdentifiers": false, + "disallowAdditionalPropertiesIfNotPresent": false, + "ensureUniqueParams": true, + "enumUnknownDefaultCase": false, + "gemAuthor": "Carla Urrea Stabile, Steven Hobbs", + "gemAuthorEmail": "hello@carlastabile.tech", + "gemHomepage": "https://github.com/carlastabile/openfga-ruby-sdk", + "gemLicense": "Apache-2.0", + "gemMetadata": {}, + "gemName": "openfga", + "gemRequiredRubyVersion": ">=3.2", + "gemSummary": "This is community-driven Ruby SDK for OpenFGA. It provides a wrapper around the [OpenFGA API definition](https://openfga.dev/api).", + "gemVersion": "0.1.5", + "hideGenerationTimestamp": true, + "library": "faraday", + "moduleName": "OpenFga", + "sortModelPropertiesByRequiredFlag": true, + "sortParamsByRequiredFlag": false, + "targetRubyVersion": "3.2", + "userAgent": "openfga-sdk ruby/$gemVersion", + "files": { + "api_model_base.mustache": { + "destinationFilename": "lib/openfga/api_model_base.rb", + "templateType": "SupportingFiles" + }, + "constants.mustache": { + "destinationFilename": "lib/openfga/constants.rb", + "templateType": "SupportingFiles" + } + } +} diff --git a/config/clients/ruby/template-source.json b/config/clients/ruby/template-source.json new file mode 100644 index 00000000..8ab41b39 --- /dev/null +++ b/config/clients/ruby/template-source.json @@ -0,0 +1,8 @@ +{ + "generator": "ruby", + "repo": "https://github.com/OpenAPITools/openapi-generator", + "branch": "master", + "commit": "695f7076bf5db8b0a6a55bf0569385e3d63f18e8", + "url": "https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator/src/main/resources/ruby-client", + "docs": "https://github.com/OpenAPITools/openapi-generator/blob/master/docs/generators/ruby.md" +} diff --git a/config/clients/ruby/template/README_api_endpoints.mustache b/config/clients/ruby/template/README_api_endpoints.mustache new file mode 100644 index 00000000..1b23e97f --- /dev/null +++ b/config/clients/ruby/template/README_api_endpoints.mustache @@ -0,0 +1,4 @@ +Class | Method | HTTP request | Description +------------ | ------------- | ------------- | ------------- +{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}} +{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}} \ No newline at end of file diff --git a/config/clients/ruby/template/README_calling_api.mustache b/config/clients/ruby/template/README_calling_api.mustache new file mode 100644 index 00000000..0bb984ae --- /dev/null +++ b/config/clients/ruby/template/README_calling_api.mustache @@ -0,0 +1,554 @@ +# OpenFga Client Methods + +#### Stores + +##### List Stores + +Get a paginated list of stores. + +[API Documentation]({{apiDocsUrl}}#/Stores/ListStores) + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +options = { page_size: 25, continuation_token: "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==" } +response = fga_client.list_stores(options) +# response = ListStoresResponse(...) +# response.stores = [Store(id: "01FQH7V8BEG3GPQW93KTRFR8JB", name: "FGA Demo Store", created_at: "2022-01-01T00:00:00.000Z", updated_at: "2022-01-01T00:00:00.000Z")] +``` + +##### Create Store + +Create and initialize a store. + +[API Documentation]({{apiDocsUrl}}#/Stores/CreateStore) + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +body = { + name: "FGA Demo Store" +} +response = fga_client.create_store(body) +# response.id = "01FQH7V8BEG3GPQW93KTRFR8JB" +``` + +##### Get Store + +Get information about the current store. + +[API Documentation]({{apiDocsUrl}}#/Stores/GetStore) + +> Requires a client initialized with a store_id + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +response = fga_client.get_store() +# response = OpenFga::GetStoreResponse(id: "01FQH7V8BEG3GPQW93KTRFR8JB", name: "FGA Demo Store", created_at: "2022-01-01T00:00:00.000Z", updated_at: "2022-01-01T00:00:00.000Z") +``` + +##### Delete Store + +Delete a store. + +[API Documentation]({{apiDocsUrl}}#/Stores/DeleteStore) + +> Requires a client initialized with a store_id + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +response = fga_client.delete_store() +# nil +``` + +#### Authorization Models + +##### Read Authorization Models + +Read all authorization models in the store. + +[API Documentation]({{apiDocsUrl}}#/Authorization%20Models/ReadAuthorizationModels) + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +options = { page_size: 25, continuation_token: "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==" } +response = fga_client.read_authorization_models(options) +# response.authorization_models = [OpenFga::AuthorizationModel(id: '01GXSA8YR785C4FYS3C0RTG7B1', schema_version: '1.1', type_definitions: type_definitions[...]), OpenFga::AuthorizationModel(id: '01GXSBM5PVYHCJNRNKXMB4QZTW', schema_version: '1.1', type_definitions: type_definitions[...])] +``` + +##### Write Authorization Model + +Create a new authorization model. + +[API Documentation]({{apiDocsUrl}}#/Authorization%20Models/WriteAuthorizationModel) + +> Note: To learn how to build your authorization model, check the Docs at {{docsUrl}}. + +> Learn more about [the {{appTitleCaseName}} configuration language]({{docsUrl}}/configuration-language). + +> You can use the [{{appTitleCaseName}} Syntax Transformer](https://github.com/openfga/syntax-transformer) to convert between the friendly DSL and the JSON authorization model. + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +type_definitions = [ + { + type: "user" + }, + { + type: "document", + relations: { + writer: { this: {} }, + viewer: { + union: { + child: [ + { this: {} }, + { + computed_userset: { + object: "", + relation: "writer" + } + } + ] + } + } + }, + metadata: { + relations: { + writer: { + directly_related_user_types: [ + { type: "user" }, + { type: "user", condition: "ViewCountLessThan200" } + ] + }, + viewer: { + directly_related_user_types: [ + { type: "user" } + ] + } + } + } + } +] + +conditions = { + ViewCountLessThan200: { + name: "ViewCountLessThan200", + expression: "ViewCount < 200", + parameters: { + ViewCount: { + type_name: "TYPE_NAME_INT" + }, + Type: { + type_name: "TYPE_NAME_STRING" + }, + Name: { + type_name: "TYPE_NAME_STRING" + } + } + } +} + +body = { + schema_version: "1.1", + type_definitions: type_definitions, + conditions: conditions +} + +response = fga_client.write_authorization_model(body) +# response.authorization_model_id = "01GXSA8YR785C4FYS3C0RTG7B1" +``` + +##### Read a Single Authorization Model + +Read a particular authorization model. + +[API Documentation]({{apiDocsUrl}}#/Authorization%20Models/ReadAuthorizationModel) + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +options = { + # You can rely on the model id set in the configuration or override it for this specific request + authorization_model_id: "01GXSA8YR785C4FYS3C0RTG7B1" +} + +response = fga_client.read_authorization_model(options) +# response.authorization_model = OpenFga::AuthorizationModel(id: '01GXSA8YR785C4FYS3C0RTG7B1', schema_version: '1.1', type_definitions: type_definitions[...]) +``` + +#### Relationship Tuples + +##### Read Relationship Tuple Changes (Watch) + +Reads the list of historical relationship tuple writes and deletes. + +[API Documentation]({{apiDocsUrl}}#/Relationship%20Tuples/ReadChanges) + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +options = { + page_size: 25, + continuation_token: "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==" +} + +response = fga_client.read_changes(options) +# response.continuation_token = ... +# response.changes = [TupleChange(tuple_key: TupleKey(object: "...", relation: "...", user: "..."), operation: TupleOperation("TUPLE_OPERATION_WRITE"), timestamp: ...)] +``` + +##### Read Relationship Tuples + +Reads the relationship tuples stored in the database. It does not evaluate nor exclude invalid tuples according to the authorization model. + +[API Documentation]({{apiDocsUrl}}#/Relationship%20Tuples/Read) + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +# Find if a relationship tuple stating that a certain user is a viewer of certain document +body = { + user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + relation: "viewer", + object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a" +} + +response = fga_client.read(body) +# response = ReadResponse(tuples: [Tuple(key: TupleKey(user: "...", relation: "...", object: "..."), timestamp: ...)]) +``` + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +# Find all relationship tuples where a certain user has a relationship as any relation to a certain document +body = { + user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a" +} + +response = fga_client.read(body) +# response = ReadResponse(tuples: [Tuple(key: TupleKey(user: "...", relation: "...", object: "..."), timestamp: ...)]) +``` + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +# Find all relationship tuples where a certain user is a viewer of any document +body = { + user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + relation: "viewer", + object: "document:" +} + +response = fga_client.read(body) +# response = ReadResponse(tuples: [Tuple(key: TupleKey(user: "...", relation: "...", object: "..."), timestamp: ...)]) +``` + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +# Find all relationship tuples where any user has a relationship as any relation with a particular document +body = { + object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a" +} + +response = fga_client.read(body) +# response = ReadResponse(tuples: [Tuple(key: TupleKey(user: "...", relation: "...", object: "..."), timestamp: ...)]) +``` + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +# Read all stored relationship tuples +body = {} + +response = fga_client.read(body) +# response = ReadResponse(tuples: [Tuple(key: TupleKey(user: "...", relation: "...", object: "..."), timestamp: ...)]) +``` + +##### Write (Create and Delete) Relationship Tuples + +Create and/or delete relationship tuples to update the system state. + +[API Documentation]({{apiDocsUrl}}#/Relationship%20Tuples/Write) + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +body = { + writes: { + tuple_keys: [ + { + user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + relation: "viewer", + object: "doc:0192ab2a-d83f-756d-9397-c5ed9f3cb69a" + }, + { + user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + relation: "viewer", + object: "doc:0192ab2d-d36e-7cb3-a4a8-5d1d67a300c5" + } + ] + }, + deletes: { + tuple_keys: [ + { + user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + relation: "writer", + object: "doc:0192ab2a-d83f-756d-9397-c5ed9f3cb69a" + } + ] + }, + opts: { + # You can rely on the model id set in the configuration or override it for this specific request + authorization_model_id: "01GXSA8YR785C4FYS3C0RTG7B1" + } +} + +response = fga_client.write(body) +``` + +#### Relationship Queries + +##### Check + +Check if a user has a particular relation with an object. + +[API Documentation]({{apiDocsUrl}}#/Relationship%20Queries/Check) + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +body = { + user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + relation: "writer", + object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a", + opts: { + # You can rely on the model id set in the configuration or override it for this specific request + authorization_model_id: "01GXSA8YR785C4FYS3C0RTG7B1", + context: { + ViewCount: 100 + } + } +} + +response = fga_client.check(body) +# response.allowed = true +``` + +##### Batch Check + +Performs multiple relationship checks in a single batch request. + +[API Documentation]({{apiDocsUrl}}#/Relationship%20Queries/BatchCheck) + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +body = { + checks: [ + { + tuple_key: { + user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + relation: "viewer", + object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a" + }, + correlation_id: "check-1", + contextual_tuples: { + tuple_keys: [ + { + user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + relation: "editor", + object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a" + } + ] + }, + context: { + ViewCount: 100 + } + }, + { + tuple_key: { + user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + relation: "admin", + object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a" + }, + correlation_id: "check-2" + } + ], + opts: { + authorization_model_id: "01GXSA8YR785C4FYS3C0RTG7B1", + max_parallel_requests: 10, + max_batch_size: 50 + } +} + +response = fga_client.batch_check(body) +# response.result contains the results mapped by correlation_id +``` + +#### Expand + +Expands the relationships in userset tree format. + +[API Documentation]({{apiDocsUrl}}#/Relationship%20Queries/Expand) + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +body = { + relation: "viewer", + object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a", + opts: { + # You can rely on the model id set in the configuration or override it for this specific request + authorization_model_id: "01GXSA8YR785C4FYS3C0RTG7B1" + } +} + +response = fga_client.expand(body) +# response = ExpandResponse(tree: UsersetTree(root: Node(name: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a#viewer", leaf: Leaf(users: Users(users: ["user:81684243-9356-4421-8fbf-a4f8d36aa31b", "user:f52a4f7a-054d-47ff-bb6e-3ac81269988f"]))))) +``` + +#### List Objects + +List the objects of a particular type a user has access to. + +[API Documentation]({{apiDocsUrl}}#/Relationship%20Queries/ListObjects) + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +body = { + user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + relation: "viewer", + type: "document", + contextual_tuples: { + tuple_keys: [ + { + user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + relation: "writer", + object: "document:0192ab2d-d36e-7cb3-a4a8-5d1d67a300c5" + } + ] + }, + context: { + ViewCount: 100 + }, + opts: { + # You can rely on the model id set in the configuration or override it for this specific request + authorization_model_id: "01GXSA8YR785C4FYS3C0RTG7B1" + } +} + +response = fga_client.list_objects(body) +# response.objects = ["document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"] +``` + +#### List Users + +List the users who have a certain relation to a particular type. + +[API Documentation](https://openfga.dev/api/service#/Relationship%20Queries/ListUsers) + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +body = { + relation: "can_read", + object: "document:2021-budget", + user_filters: [ + { type: "user" }, + { type: "team", relation: "member" } + ], + contextual_tuples: [ + { + user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + relation: "editor", + object: "folder:product" + }, + { + user: "folder:product", + relation: "parent", + object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a" + } + ], + context: {}, + opts: { + authorization_model_id: "01GXSA8YR785C4FYS3C0RTG7B1" + } +} + +response = fga_client.list_users(body) +# response.users = [{object: {type: "user", id: "81684243-9356-4421-8fbf-a4f8d36aa31b"}}, {userset: {type: "user"}}, ...] +``` + +#### Assertions + +##### Read Assertions + +Read assertions for a particular authorization model. + +[API Documentation]({{apiDocsUrl}}#/Assertions/Read%20Assertions) + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +options = { + # You can rely on the model id set in the configuration or override it for this specific request + authorization_model_id: "01GXSA8YR785C4FYS3C0RTG7B1" +} + +response = fga_client.read_assertions(options) +``` + +##### Write Assertions + +Update the assertions for a particular authorization model. + +[API Documentation]({{apiDocsUrl}}#/Assertions/Write%20Assertions) + +```ruby +# Initialize the fga_client +# fga_client = OpenFga::SdkClient.new(configuration) + +body = { + assertions: [ + { + user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + relation: "viewer", + object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a", + expectation: true + } + ], + opts: { + # You can rely on the model id set in the configuration or override it for this specific request + authorization_model_id: "01GXSA8YR785C4FYS3C0RTG7B1" + } +} + +response = fga_client.write_assertions(body) +``` diff --git a/config/clients/ruby/template/README_custom_badges.mustache b/config/clients/ruby/template/README_custom_badges.mustache new file mode 100644 index 00000000..e69de29b diff --git a/config/clients/ruby/template/README_initializing.mustache b/config/clients/ruby/template/README_initializing.mustache new file mode 100644 index 00000000..a3674115 --- /dev/null +++ b/config/clients/ruby/template/README_initializing.mustache @@ -0,0 +1,105 @@ +We strongly recommend you initialize the `SdkClient` only once and then re-use it +throughout your app, otherwise you will incur the cost of having to re-initialize +multiple times or at every request, the cost of reduced connection pooling and +re-use, and would be particularly costly in the client credentials flow, +as that flow will be performed on every request. + +#### No Credentials + +```ruby +require 'openfga' + +def main + # Initialize the fga_client + fga_client = OpenFga::SdkClient.new( + api_url: ENV['FGA_API_URL'], # required + store_id: ENV['FGA_STORE_ID'], # optional, not needed when calling `create_store` or `list_stores` + authorization_model_id: ENV['FGA_MODEL_ID'] # optional, can be overridden per request + ) + + api_response = fga_client.read_authorization_models() + return api_response +end +``` + +#### API Token + +```ruby +require 'openfga' + +def main + # Initialize the fga_client + fga_client = OpenFga::SdkClient.new( + api_url: ENV['FGA_API_URL'], # required + store_id: ENV['FGA_STORE_ID'], # optional, not needed when calling `create_store` or `list_stores` + authorization_model_id: ENV['FGA_MODEL_ID'], # optional, can be overridden per request + credentials: { + method: :api_token, + api_token: ENV['FGA_API_TOKEN'] + } + ) + + api_response = fga_client.read_authorization_models() + return api_response +end +``` + +#### Client Credentials + +```ruby +require 'openfga' + +def main + # Initialize the fga_client + fga_client = OpenFga::SdkClient.new( + api_url: ENV['FGA_API_URL'], # required + store_id: ENV['FGA_STORE_ID'], # optional, not needed when calling `create_store` or `list_stores` + authorization_model_id: ENV['FGA_MODEL_ID'], # optional, can be overridden per request + credentials: { + method: :client_credentials, + api_token_issuer: ENV['FGA_API_TOKEN_ISSUER'], + api_audience: ENV['FGA_API_AUDIENCE'], + client_id: ENV['FGA_CLIENT_ID'], + client_secret: ENV['FGA_CLIENT_SECRET'] + } + ) + + api_response = fga_client.read_authorization_models() + return api_response +end +``` + +### Custom Headers + +#### Per-Request Headers + +You can send custom headers on a per-request basis by using the `opts` parameter. Per-request headers will override any default headers with the same name. + +```ruby +require 'openfga' + +def main + # Initialize the fga_client + fga_client = OpenFga::SdkClient.new( + api_url: ENV['FGA_API_URL'], + store_id: ENV['FGA_STORE_ID'], + authorization_model_id: ENV['FGA_MODEL_ID'] + ) + + # Add custom headers to a specific request + result = fga_client.check( + user: "user:anne", + relation: "viewer", + object: "document:roadmap", + opts: { + header_params: { + "X-Request-ID": "123e4567-e89b-12d3-a456-426614174000", + "X-Custom-Header": "custom-value" + } + } + ) + + return result +end +``` + diff --git a/config/clients/ruby/template/README_installation.mustache b/config/clients/ruby/template/README_installation.mustache new file mode 100644 index 00000000..0f73f6a5 --- /dev/null +++ b/config/clients/ruby/template/README_installation.mustache @@ -0,0 +1,24 @@ +To install: + +``` +gem install {{gemName}} +``` + +Alternatively, you can add it to your `Gemfile`: + +``` +gem '{{gemName}}' +``` + +Then run `bundle install` to install the gem. + +To use in your code, require the gem and create the configuration: + +``` +require '{{gemName}}' + +sdk_config = { + api_url: 'http://localhost:8080' +} +``` + diff --git a/config/clients/ruby/template/README_license_disclaimer.mustache b/config/clients/ruby/template/README_license_disclaimer.mustache new file mode 100644 index 00000000..e69de29b diff --git a/config/clients/ruby/template/README_models.mustache b/config/clients/ruby/template/README_models.mustache new file mode 100644 index 00000000..4e57e913 --- /dev/null +++ b/config/clients/ruby/template/README_models.mustache @@ -0,0 +1,3 @@ +{{#models}}{{#model}} - [{{{classname}}}]({{modelDocPath}}{{{classname}}}.md) +{{/model}}{{/models}} + diff --git a/config/clients/ruby/template/Rakefile.mustache b/config/clients/ruby/template/Rakefile.mustache new file mode 100644 index 00000000..c72ca30d --- /dev/null +++ b/config/clients/ruby/template/Rakefile.mustache @@ -0,0 +1,10 @@ +require "bundler/gem_tasks" + +begin + require 'rspec/core/rake_task' + + RSpec::Core::RakeTask.new(:spec) + task default: :spec +rescue LoadError + # no rspec available +end diff --git a/config/clients/ruby/template/api.mustache b/config/clients/ruby/template/api.mustache new file mode 100644 index 00000000..d15c8b54 --- /dev/null +++ b/config/clients/ruby/template/api.mustache @@ -0,0 +1,256 @@ +=begin +{{> api_info}} + +=end + +require 'cgi' + +module {{moduleName}} +{{#operations}} + class {{classname}} + attr_accessor :api_client + + def initialize(api_client = ApiClient.default) + @api_client = api_client + end +{{#operation}} + {{#summary}} + # {{{.}}} + {{/summary}} + {{#notes}} + # {{{.}}} + {{/notes}} +{{#vendorExtensions.x-group-parameters}} + # @param [Hash] opts the parameters +{{#allParams}} +{{#required}} + # @option opts [{{{dataType}}}] :{{paramName}} {{description}} (required) +{{/required}} +{{/allParams}} +{{/vendorExtensions.x-group-parameters}} +{{^vendorExtensions.x-group-parameters}} +{{#allParams}} +{{#required}} + # @param {{paramName}} [{{{dataType}}}] {{description}} +{{/required}} +{{/allParams}} + # @param [Hash] opts the optional parameters +{{/vendorExtensions.x-group-parameters}} +{{#allParams}} +{{^required}} + # @option opts [{{{dataType}}}] :{{paramName}} {{description}}{{#defaultValue}} (default to {{{.}}}){{/defaultValue}} +{{/required}} +{{/allParams}} + # @return [{{{returnType}}}{{^returnType}}nil{{/returnType}}] + def {{operationId}}({{^vendorExtensions.x-group-parameters}}{{#allParams}}{{#required}}{{paramName}}, {{/required}}{{/allParams}}{{/vendorExtensions.x-group-parameters}}opts = {}) + {{#returnType}}data, _status_code, _headers = {{/returnType}}{{operationId}}_with_http_info({{^vendorExtensions.x-group-parameters}}{{#allParams}}{{#required}}{{paramName}}, {{/required}}{{/allParams}}{{/vendorExtensions.x-group-parameters}}opts) + {{#returnType}}data{{/returnType}}{{^returnType}}nil{{/returnType}} + end + + {{#summary}} + # {{.}} + {{/summary}} + {{#notes}} + # {{.}} + {{/notes}} +{{#vendorExtensions.x-group-parameters}} + # @param [Hash] opts the parameters +{{#allParams}} +{{#required}} + # @option opts [{{{dataType}}}] :{{paramName}} {{description}} (required) +{{/required}} +{{/allParams}} +{{/vendorExtensions.x-group-parameters}} +{{^vendorExtensions.x-group-parameters}} +{{#allParams}} +{{#required}} + # @param {{paramName}} [{{{dataType}}}] {{description}} +{{/required}} +{{/allParams}} + # @param [Hash] opts the optional parameters +{{/vendorExtensions.x-group-parameters}} +{{#allParams}} +{{^required}} + # @option opts [{{{dataType}}}] :{{paramName}} {{description}}{{#defaultValue}} (default to {{{.}}}){{/defaultValue}} +{{/required}} +{{/allParams}} + # @return [Array<({{{returnType}}}{{^returnType}}nil{{/returnType}}, Integer, Hash)>] {{#returnType}}{{{.}}} data{{/returnType}}{{^returnType}}nil{{/returnType}}, response status code and response headers + def {{operationId}}_with_http_info({{^vendorExtensions.x-group-parameters}}{{#allParams}}{{#required}}{{paramName}}, {{/required}}{{/allParams}}{{/vendorExtensions.x-group-parameters}}opts = {}) + if @api_client.config.debugging + @api_client.config.logger.debug 'Calling API: {{classname}}.{{operationId}} ...' + end + {{#vendorExtensions.x-group-parameters}} + # unbox the parameters from the hash + {{#allParams}} + {{^isNullable}} + {{#required}} + {{{paramName}}} = opts[:'{{{paramName}}}'] + {{/required}} + {{/isNullable}} + {{/allParams}} + {{/vendorExtensions.x-group-parameters}} + {{#allParams}} + {{^isNullable}} + {{#required}} + # verify the required parameter '{{paramName}}' is set + if @api_client.config.client_side_validation && {{{paramName}}}.nil? + fail ArgumentError, "Missing the required parameter '{{paramName}}' when calling {{classname}}.{{operationId}}" + end + {{#isEnum}} + {{^isContainer}} + # verify enum value + allowable_values = [{{#allowableValues}}{{#enumVars}}{{{value}}}{{^-last}}, {{/-last}}{{/enumVars}}{{/allowableValues}}] + if @api_client.config.client_side_validation && !allowable_values.include?({{{paramName}}}) + fail ArgumentError, "invalid value for \"{{{paramName}}}\", must be one of #{allowable_values}" + end + {{/isContainer}} + {{/isEnum}} + {{/required}} + {{/isNullable}} + {{^required}} + {{#isEnum}} + {{#collectionFormat}} + allowable_values = [{{#allowableValues}}{{#enumVars}}{{{value}}}{{^-last}}, {{/-last}}{{/enumVars}}{{/allowableValues}}] + if @api_client.config.client_side_validation && opts[:'{{{paramName}}}'] && !opts[:'{{{paramName}}}'].all? { |item| allowable_values.include?(item) } + fail ArgumentError, "invalid value for \"{{{paramName}}}\", must include one of #{allowable_values}" + end + {{/collectionFormat}} + {{^collectionFormat}} + allowable_values = [{{#allowableValues}}{{#enumVars}}{{{value}}}{{^-last}}, {{/-last}}{{/enumVars}}{{/allowableValues}}] + if @api_client.config.client_side_validation && opts[:'{{{paramName}}}'] && !allowable_values.include?(opts[:'{{{paramName}}}']) + fail ArgumentError, "invalid value for \"{{{paramName}}}\", must be one of #{allowable_values}" + end + {{/collectionFormat}} + {{/isEnum}} + {{/required}} + {{#hasValidation}} + {{#maxLength}} + if @api_client.config.client_side_validation && {{^required}}!opts[:'{{{paramName}}}'].nil? && {{/required}}{{#required}}{{{paramName}}}{{/required}}{{^required}}opts[:'{{{paramName}}}']{{/required}}.to_s.length > {{{maxLength}}} + fail ArgumentError, 'invalid value for "{{#required}}{{{paramName}}}{{/required}}{{^required}}opts[:"{{{paramName}}}"]{{/required}}" when calling {{classname}}.{{operationId}}, the character length must be smaller than or equal to {{{maxLength}}}.' + end + + {{/maxLength}} + {{#minLength}} + if @api_client.config.client_side_validation && {{^required}}!opts[:'{{{paramName}}}'].nil? && {{/required}}{{#required}}{{{paramName}}}{{/required}}{{^required}}opts[:'{{{paramName}}}']{{/required}}.to_s.length < {{{minLength}}} + fail ArgumentError, 'invalid value for "{{#required}}{{{paramName}}}{{/required}}{{^required}}opts[:"{{{paramName}}}"]{{/required}}" when calling {{classname}}.{{operationId}}, the character length must be greater than or equal to {{{minLength}}}.' + end + + {{/minLength}} + {{#maximum}} + if @api_client.config.client_side_validation && {{^required}}!opts[:'{{{paramName}}}'].nil? && {{/required}}{{#required}}{{{paramName}}}{{/required}}{{^required}}opts[:'{{{paramName}}}']{{/required}} >{{#exclusiveMaximum}}={{/exclusiveMaximum}} {{{maximum}}} + fail ArgumentError, 'invalid value for "{{#required}}{{{paramName}}}{{/required}}{{^required}}opts[:"{{{paramName}}}"]{{/required}}" when calling {{classname}}.{{operationId}}, must be smaller than {{^exclusiveMaximum}}or equal to {{/exclusiveMaximum}}{{{maximum}}}.' + end + + {{/maximum}} + {{#minimum}} + if @api_client.config.client_side_validation && {{^required}}!opts[:'{{{paramName}}}'].nil? && {{/required}}{{#required}}{{{paramName}}}{{/required}}{{^required}}opts[:'{{{paramName}}}']{{/required}} <{{#exclusiveMinimum}}={{/exclusiveMinimum}} {{{minimum}}} + fail ArgumentError, 'invalid value for "{{#required}}{{{paramName}}}{{/required}}{{^required}}opts[:"{{{paramName}}}"]{{/required}}" when calling {{classname}}.{{operationId}}, must be greater than {{^exclusiveMinimum}}or equal to {{/exclusiveMinimum}}{{{minimum}}}.' + end + + {{/minimum}} + {{#pattern}} + pattern = Regexp.new({{{pattern}}}) + if @api_client.config.client_side_validation && {{^required}}!opts[:'{{{paramName}}}'].nil? && {{/required}}{{#required}}{{{paramName}}}{{/required}}{{^required}}opts[:'{{{paramName}}}']{{/required}} !~ pattern + fail ArgumentError, "invalid value for '{{#required}}{{{paramName}}}{{/required}}{{^required}}opts[:\"{{{paramName}}}\"]{{/required}}' when calling {{classname}}.{{operationId}}, must conform to the pattern #{pattern}." + end + + {{/pattern}} + {{#maxItems}} + if @api_client.config.client_side_validation && {{^required}}!opts[:'{{{paramName}}}'].nil? && {{/required}}{{#required}}{{{paramName}}}{{/required}}{{^required}}opts[:'{{{paramName}}}']{{/required}}.length > {{{maxItems}}} + fail ArgumentError, 'invalid value for "{{#required}}{{{paramName}}}{{/required}}{{^required}}opts[:"{{{paramName}}}"]{{/required}}" when calling {{classname}}.{{operationId}}, number of items must be less than or equal to {{{maxItems}}}.' + end + + {{/maxItems}} + {{#minItems}} + if @api_client.config.client_side_validation && {{^required}}!opts[:'{{{paramName}}}'].nil? && {{/required}}{{#required}}{{{paramName}}}{{/required}}{{^required}}opts[:'{{{paramName}}}']{{/required}}.length < {{{minItems}}} + fail ArgumentError, 'invalid value for "{{#required}}{{{paramName}}}{{/required}}{{^required}}opts[:"{{{paramName}}}"]{{/required}}" when calling {{classname}}.{{operationId}}, number of items must be greater than or equal to {{{minItems}}}.' + end + + {{/minItems}} + {{/hasValidation}} + {{/allParams}} + # resource path + local_var_path = '{{{path}}}'{{#pathParams}}.sub('{' + '{{baseName}}' + '}', CGI.escape({{paramName}}.to_s){{^strictSpecBehavior}}.gsub('%2F', '/'){{/strictSpecBehavior}}){{/pathParams}} + + # query parameters + query_params = opts[:query_params] || {} + {{#queryParams}} + {{#required}} + query_params[:'{{{baseName}}}'] = {{#collectionFormat}}@api_client.build_collection_param({{{paramName}}}, :{{{collectionFormat}}}){{/collectionFormat}}{{^collectionFormat}}{{{paramName}}}{{/collectionFormat}} + {{/required}} + {{/queryParams}} + {{#queryParams}} + {{^required}} + query_params[:'{{{baseName}}}'] = {{#collectionFormat}}@api_client.build_collection_param(opts[:'{{{paramName}}}'], :{{{collectionFormat}}}){{/collectionFormat}}{{^collectionFormat}}opts[:'{{{paramName}}}']{{/collectionFormat}} if !opts[:'{{{paramName}}}'].nil? + {{/required}} + {{/queryParams}} + + # header parameters + header_params = opts[:header_params] || {} + {{#hasProduces}} + # HTTP header 'Accept' (if needed) + header_params['Accept'] = @api_client.select_header_accept([{{#produces}}'{{{mediaType}}}'{{^-last}}, {{/-last}}{{/produces}}]) unless header_params['Accept'] + {{/hasProduces}} + {{#hasConsumes}} + # HTTP header 'Content-Type' + content_type = @api_client.select_header_content_type([{{#consumes}}'{{{mediaType}}}'{{^-last}}, {{/-last}}{{/consumes}}]) + if !content_type.nil? + header_params['Content-Type'] = content_type + end + {{/hasConsumes}} + {{#headerParams}} + {{#required}} + header_params[{{#lambdaFixHeaderKey}}:'{{{baseName}}}'{{/lambdaFixHeaderKey}}] = {{#collectionFormat}}@api_client.build_collection_param({{{paramName}}}, :{{{collectionFormat}}}){{/collectionFormat}}{{^collectionFormat}}{{{paramName}}}{{/collectionFormat}} + {{/required}} + {{/headerParams}} + {{#headerParams}} + {{^required}} + header_params[{{#lambdaFixHeaderKey}}:'{{{baseName}}}'{{/lambdaFixHeaderKey}}] = {{#collectionFormat}}@api_client.build_collection_param(opts[:'{{{paramName}}}'], :{{{collectionFormat}}}){{/collectionFormat}}{{^collectionFormat}}opts[:'{{{paramName}}}']{{/collectionFormat}} if !opts[:'{{{paramName}}}'].nil? + {{/required}} + {{/headerParams}} + + # form parameters + form_params = opts[:form_params] || {} + {{#formParams}} + {{#required}} + form_params['{{baseName}}'] = {{#collectionFormat}}@api_client.build_collection_param({{{paramName}}}, :{{{collectionFormat}}}){{/collectionFormat}}{{^collectionFormat}}{{{paramName}}}{{/collectionFormat}} + {{/required}} + {{/formParams}} + {{#formParams}} + {{^required}} + form_params['{{baseName}}'] = {{#collectionFormat}}@api_client.build_collection_param(opts[:'{{{paramName}}}'], :{{{collectionFormat}}}){{/collectionFormat}}{{^collectionFormat}}opts[:'{{{paramName}}}']{{/collectionFormat}} if !opts[:'{{paramName}}'].nil? + {{/required}} + {{/formParams}} + + # http body (model) + post_body = opts[:debug_body]{{#bodyParam}} || @api_client.object_to_http_body({{#required}}{{{paramName}}}{{/required}}{{^required}}opts[:'{{{paramName}}}']{{/required}}){{/bodyParam}} + + # return_type + return_type = opts[:debug_return_type]{{#returnType}} || '{{{.}}}'{{/returnType}} + + # auth_names + auth_names = opts[:debug_auth_names] || [{{#authMethods}}'{{name}}'{{^-last}}, {{/-last}}{{/authMethods}}] + + new_options = opts.merge( + :operation => :"{{classname}}.{{operationId}}", + :header_params => header_params, + :query_params => query_params, + :form_params => form_params, + :body => post_body, + :auth_names => auth_names, + :return_type => return_type + ) + + data, status_code, headers = @api_client.call_api(:{{httpMethod}}, local_var_path, new_options) + if @api_client.config.debugging + @api_client.config.logger.debug "API called: {{classname}}#{{operationId}}\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}" + end + return data, status_code, headers + end +{{^-last}} + +{{/-last}} +{{/operation}} + end +{{/operations}} +end diff --git a/config/clients/ruby/template/api_client.mustache b/config/clients/ruby/template/api_client.mustache new file mode 100644 index 00000000..ac2827bf --- /dev/null +++ b/config/clients/ruby/template/api_client.mustache @@ -0,0 +1,254 @@ +=begin +{{> api_info}} + +=end + +require 'date' +require 'json' +require 'logger' +require 'tempfile' +require 'time' +{{#isTyphoeus}} +require 'typhoeus' +{{/isTyphoeus}} +{{#isFaraday}} +require 'faraday' +require 'faraday/multipart' if Gem::Version.new(Faraday::VERSION) >= Gem::Version.new('2.0') +require 'marcel' +{{/isFaraday}} +{{#isHttpx}} +require 'httpx' +require 'net/http/status' +{{/isHttpx}} + + +module {{moduleName}} + class ApiClient + # The Configuration object holding settings to be used in the API client. + attr_accessor :config + + # Defines the headers to be used in HTTP requests of all API calls by default. + # + # @return [Hash] + attr_accessor :default_headers + + # Initializes the ApiClient + # @option config [Configuration] Configuration for initializing the object, default to Configuration.default + def initialize(config = Configuration.default) + @config = config + @user_agent = "{{{httpUserAgent}}}{{^httpUserAgent}}OpenAPI-Generator/#{ {{moduleName}}::VERSION }/ruby{{/httpUserAgent}}" + @default_headers = { + 'Content-Type' => 'application/json', + 'User-Agent' => @user_agent + } + end + + def self.default + @@default ||= ApiClient.new + end + +{{#isTyphoeus}} +{{> api_client_typhoeus_partial}} + +{{/isTyphoeus}} +{{#isFaraday}} +{{> api_client_faraday_partial}} + +{{/isFaraday}} +{{#isHttpx}} +{{> api_client_httpx_partial}} + +{{/isHttpx}} + # Check if the given MIME is a JSON MIME. + # JSON MIME examples: + # application/json + # application/json; charset=UTF8 + # APPLICATION/JSON + # */* + # @param [String] mime MIME + # @return [Boolean] True if the MIME is application/json + def json_mime?(mime) + (mime == '*/*') || !(mime =~ /^Application\/.*json(?!p)(;.*)?/i).nil? + end + + # Deserialize the response to the given return type. + # + # @param [Response] response HTTP response + # @param [String] return_type some examples: "User", "Array", "Hash" + def deserialize(response, return_type) + body = response.body + return nil if body.nil? || body.empty? + + # return response body directly for String return type + return body.to_s if return_type == 'String' + + # ensuring a default content type + content_type = response.headers['Content-Type'] || 'application/json' + + fail "Content-Type is not supported: #{content_type}" unless json_mime?(content_type) + + begin + data = JSON.parse("[#{body}]", :symbolize_names => true)[0] + rescue JSON::ParserError => e + if %w(String Date Time).include?(return_type) + data = body + else + raise e + end + end + + convert_to_type data, return_type + end + + # Convert data to the given return type. + # @param [Object] data Data to be converted + # @param [String] return_type Return type + # @return [Mixed] Data in a particular type + def convert_to_type(data, return_type) + return nil if data.nil? + case return_type + when 'String' + data.to_s + when 'Integer' + data.to_i + when 'Float' + data.to_f + when 'Boolean' + data == true + when 'Time' + # parse date time (expecting ISO 8601 format) + Time.parse data + when 'Date' + # parse date time (expecting ISO 8601 format) + Date.parse data + when 'Object' + # generic object (usually a Hash), return directly + data + when /\AArray<(.+)>\z/ + # e.g. Array + sub_type = $1 + data.map { |item| convert_to_type(item, sub_type) } + when /\AHash\\z/ + # e.g. Hash + sub_type = $1 + {}.tap do |hash| + data.each { |k, v| hash[k] = convert_to_type(v, sub_type) } + end + else + # models (e.g. Pet) or oneOf/anyOf + klass = {{moduleName}}.const_get(return_type) + if klass.respond_to?(:openapi_one_of) || klass.respond_to?(:openapi_any_of) + klass.build(data) + else + klass.build_from_hash(data) + end + end + end + + # Sanitize filename by removing path. + # e.g. ../../sun.gif becomes sun.gif + # + # @param [String] filename the filename to be sanitized + # @return [String] the sanitized filename + def sanitize_filename(filename) + filename.split(/[\/\\]/).last + end + + def build_request_url(path, opts = {}) + # Add leading and trailing slashes to path + path = "/#{path}".gsub(/\/+/, '/') + @config.base_url(opts[:operation]) + path + end + + # Update header and query params based on authentication settings. + # + # @param [Hash] header_params Header parameters + # @param [Hash] query_params Query parameters + # @param [String] auth_names Authentication scheme name + def update_params_for_auth!(header_params, query_params, auth_names) + Array(auth_names).each do |auth_name| + auth_setting = @config.auth_settings[auth_name] + next unless auth_setting + case auth_setting[:in] + when 'header' then header_params[auth_setting[:key]] = auth_setting[:value] + when 'query' then query_params[auth_setting[:key]] = auth_setting[:value] + else fail ArgumentError, 'Authentication token must be in `query` or `header`' + end + end + end + + # Sets user agent in HTTP header + # + # @param [String] user_agent User agent (e.g. openapi-generator/ruby/1.0.0) + def user_agent=(user_agent) + @user_agent = user_agent + @default_headers['User-Agent'] = @user_agent + end + + # Return Accept header based on an array of accepts provided. + # @param [Array] accepts array for Accept + # @return [String] the Accept header (e.g. application/json) + def select_header_accept(accepts) + return nil if accepts.nil? || accepts.empty? + # use JSON when present, otherwise use all of the provided + json_accept = accepts.find { |s| json_mime?(s) } + json_accept || accepts.join(',') + end + + # Return Content-Type header based on an array of content types provided. + # @param [Array] content_types array for Content-Type + # @return [String] the Content-Type header (e.g. application/json) + def select_header_content_type(content_types) + # return nil by default + return if content_types.nil? || content_types.empty? + # use JSON when present, otherwise use the first one + json_content_type = content_types.find { |s| json_mime?(s) } + json_content_type || content_types.first + end + + # Convert object (array, hash, object, etc) to JSON string. + # @param [Object] model object to be converted into JSON string + # @return [String] JSON string representation of the object + def object_to_http_body(model) + return model if model.nil? || model.is_a?(String) + local_body = nil + if model.is_a?(Array) + local_body = model.map { |m| object_to_hash(m) } + else + local_body = object_to_hash(model) + end + local_body.to_json + end + + # Convert object(non-array) to hash. + # @param [Object] obj object to be converted into JSON string + # @return [String] JSON string representation of the object + def object_to_hash(obj) + if obj.respond_to?(:to_hash) + obj.to_hash + else + obj + end + end + + # Build parameter value according to the given collection format. + # @param [String] collection_format one of :csv, :ssv, :tsv, :pipes and :multi + def build_collection_param(param, collection_format) + case collection_format + when :csv + param.join(',') + when :ssv + param.join(' ') + when :tsv + param.join("\t") + when :pipes + param.join('|') + when :multi + # return the array directly as typhoeus will handle it as expected + param + else + fail "unknown collection format: #{collection_format.inspect}" + end + end + end +end diff --git a/config/clients/ruby/template/api_client_faraday_partial.mustache b/config/clients/ruby/template/api_client_faraday_partial.mustache new file mode 100644 index 00000000..11ae6450 --- /dev/null +++ b/config/clients/ruby/template/api_client_faraday_partial.mustache @@ -0,0 +1,200 @@ + # Call an API with given options. + # + # @return [Array<(Object, Integer, Hash)>] an array of 3 elements: + # the data deserialized from response body (could be nil), response status code and response headers. + def call_api(http_method, path, opts = {}) + stream = nil + begin + response = connection(opts).public_send(http_method.to_sym.downcase) do |req| + request = build_request(http_method, path, req, opts) + stream = download_file(request) if opts[:return_type] == 'File' || opts[:return_type] == 'Binary' + end + + if config.debugging + config.logger.debug "HTTP response body ~BEGIN~\n#{response.body}\n~END~\n" + end + + unless response.success? + if response.status == 0 && response.respond_to?(:return_message) + # Errors from libcurl will be made visible here + fail ApiError.new(code: 0, + message: response.return_message) + else + fail ApiError.new(code: response.status, + response_headers: response.headers, + response_body: response.body), + response.reason_phrase + end + end + rescue Faraday::TimeoutError + fail ApiError.new('Connection timed out') + rescue Faraday::ConnectionFailed + fail ApiError.new('Connection failed') + end + + if opts[:return_type] == 'File' || opts[:return_type] == 'Binary' + data = deserialize_file(response, stream) + elsif opts[:return_type] + data = deserialize(response, opts[:return_type]) + else + data = nil + end + return data, response.status, response.headers + end + + # Builds the HTTP request + # + # @param [String] http_method HTTP method/verb (e.g. POST) + # @param [String] path URL path (e.g. /account/new) + # @option opts [Hash] :header_params Header parameters + # @option opts [Hash] :query_params Query parameters + # @option opts [Hash] :form_params Query parameters + # @option opts [Object] :body HTTP body (JSON/XML) + # @return [Faraday::Request] A Faraday Request + def build_request(http_method, path, request, opts = {}) + url = build_request_url(path, opts) + http_method = http_method.to_sym.downcase + + header_params = @default_headers.merge(opts[:header_params] || {}) + query_params = opts[:query_params] || {} + form_params = opts[:form_params] || {} + + update_params_for_auth! header_params, query_params, opts[:auth_names] + + if [:post, :patch, :put, :delete].include?(http_method) + req_body = build_request_body(header_params, form_params, opts[:body]) + if config.debugging + config.logger.debug "HTTP request body param ~BEGIN~\n#{req_body}\n~END~\n" + end + end + request.headers = header_params + request.body = req_body + + # Overload default options only if provided + request.options.params_encoder = config.params_encoder if config.params_encoder + request.options.timeout = config.timeout if config.timeout + + request.url url + request.params = query_params + request + end + + # Builds the HTTP request body + # + # @param [Hash] header_params Header parameters + # @param [Hash] form_params Query parameters + # @param [Object] body HTTP body (JSON/XML) + # @return [String] HTTP body data in the form of string + def build_request_body(header_params, form_params, body) + # http form + if header_params['Content-Type'] == 'application/x-www-form-urlencoded' + data = URI.encode_www_form(form_params) + elsif header_params['Content-Type'] == 'multipart/form-data' + data = {} + form_params.each do |key, value| + case value + when ::File, ::Tempfile + data[key] = Faraday::FilePart.new(value.path, Marcel::MimeType.for(Pathname.new(value.path))) + when ::Array, nil + # let Faraday handle Array and nil parameters + data[key] = value + else + data[key] = value.to_s + end + end + elsif body + data = body.is_a?(String) ? body : body.to_json + else + data = nil + end + data + end + + def download_file(request) + stream = [] + + # handle streaming Responses + request.options.on_data = Proc.new do |chunk, overall_received_bytes| + stream << chunk + end + + stream + end + + def deserialize_file(response, stream) + body = response.body + encoding = body.encoding + + # reconstruct content + content = stream.join + content = content.unpack('m').join if response.headers['Content-Transfer-Encoding'] == 'binary' + content = content.force_encoding(encoding) + + # return byte stream + return content if @config.return_binary_data == true + + # return file instead of binary data + content_disposition = response.headers['Content-Disposition'] + if content_disposition && content_disposition =~ /filename=/i + filename = content_disposition[/filename=['"]?([^'"\s]+)['"]?/, 1] + prefix = sanitize_filename(filename) + else + prefix = 'download-' + end + prefix = prefix + '-' unless prefix.end_with?('-') + + tempfile = Tempfile.open(prefix, @config.temp_folder_path, encoding: encoding) + tempfile.write(content) + tempfile.close + + config.logger.info "Temp file written to #{tempfile.path}, please copy the file to a proper folder "\ + "with e.g. `FileUtils.cp(tempfile.path, '/new/file/path')` otherwise the temp file "\ + "will be deleted automatically with GC. It's also recommended to delete the temp file "\ + "explicitly with `tempfile.delete`" + tempfile + end + + def connection(opts) + opts[:header_params]['Content-Type'] == 'multipart/form-data' ? connection_multipart : connection_regular + end + + def connection_multipart + @connection_multipart ||= build_connection do |conn| + conn.request :multipart + conn.request :url_encoded + end + end + + def connection_regular + @connection_regular ||= build_connection + end + + def build_connection + Faraday.new(url: config.base_url, ssl: ssl_options, proxy: config.proxy) do |conn| + basic_auth(conn) + config.configure_middleware(conn) + yield(conn) if block_given? + conn.adapter(Faraday.default_adapter) + config.configure_connection(conn) + end + end + + def ssl_options + { + ca_file: config.ssl_ca_file, + verify: config.ssl_verify, + verify_mode: config.ssl_verify_mode, + client_cert: config.ssl_client_cert, + client_key: config.ssl_client_key + } + end + + def basic_auth(conn) + if config.username && config.password + if Gem::Version.new(Faraday::VERSION) >= Gem::Version.new('2.0') + conn.request(:authorization, :basic, config.username, config.password) + else + conn.request(:basic_auth, config.username, config.password) + end + end + end diff --git a/config/clients/ruby/template/api_client_httpx_partial.mustache b/config/clients/ruby/template/api_client_httpx_partial.mustache new file mode 100644 index 00000000..7dd5221d --- /dev/null +++ b/config/clients/ruby/template/api_client_httpx_partial.mustache @@ -0,0 +1,134 @@ + # Call an API with given options. + # + # @return [Array<(Object, Integer, Hash)>] an array of 3 elements: + # the data deserialized from response body (could be nil), response status code and response headers. + def call_api(http_method, path, opts = {}) + begin + response = build_request(http_method.to_s, path, opts) + + if config.debugging + config.logger.debug "HTTP response body ~BEGIN~\n#{response.body}\n~END~\n" + end + + response.raise_for_status + + rescue HTTPX::HTTPError + fail ApiError.new(code: response.status, + response_headers: response.headers.to_h, + response_body: response.body.to_s), + Net::HTTP::STATUS_CODES.fetch(response.status, "HTTP Error (#{response.status})") + rescue HTTPX::TimeoutError + fail ApiError.new('Connection timed out') + rescue HTTPX::ConnectionError, HTTPX::ResolveError + fail ApiError.new('Connection failed') + end + + if opts[:return_type] == 'File' + data = deserialize_file(response) + elsif opts[:return_type] + data = deserialize(response, opts[:return_type]) + else + data = nil + end + return data, response.status, response.headers.to_h + end + + # Builds the HTTP request + # + # @param [String] http_method HTTP method/verb (e.g. POST) + # @param [String] path URL path (e.g. /account/new) + # @option opts [Hash] :header_params Header parameters + # @option opts [Hash] :query_params Query parameters + # @option opts [Hash] :form_params Query parameters + # @option opts [Object] :body HTTP body (JSON/XML) + # @return [HTTPX::Request] A Request object + def build_request(http_method, path, opts = {}) + url = build_request_url(path, opts) + + header_params = @default_headers.merge(opts[:header_params] || {}) + query_params = opts[:query_params] || {} + form_params = opts[:form_params] || {} + + update_params_for_auth! header_params, query_params, opts[:auth_names] + + if %w[POST PATCH PUT DELETE].include?(http_method) + body_params = build_request_body(header_params, form_params, opts[:body]) + if config.debugging + config.logger.debug "HTTP request body param ~BEGIN~\n#{req_body}\n~END~\n" + end + end + req_opts = { + :headers => HTTPX::Headers.new(header_params) + } + req_opts.merge!(body_params) if body_params + req_opts[:params] = query_params if query_params && !query_params.empty? + session.request(http_method, url, **req_opts) + end + + # Builds the HTTP request body + # + # @param [Hash] header_params Header parameters + # @param [Hash] form_params Query parameters + # @param [Object] body HTTP body (JSON/XML) + # @return [Hash{Symbol => Object}] body options as HTTPX handles them + def build_request_body(header_params, form_params, body) + # http form + if header_params['Content-Type'] == 'application/x-www-form-urlencoded' || + header_params['Content-Type'] == 'multipart/form-data' + header_params.delete('Content-Type') # httpx takes care of this + { form: form_params } + elsif body + body.is_a?(String) ? { body: body } : { json: body } + end + end + + def deserialize_file(response) + body = response.body + if @config.return_binary_data == true + # TODO: force response encoding + body.to_s + else + content_disposition = response.headers['content-disposition'] + if content_disposition && content_disposition =~ /filename=/i + filename = content_disposition[/filename=['"]?([^'"\s]+)['"]?/, 1] + prefix = sanitize_filename(filename) + else + prefix = 'download-' + end + prefix = prefix + '-' unless prefix.end_with?('-') + encoding = response.body.encoding + tempfile = Tempfile.open(prefix, @config.temp_folder_path, encoding: encoding) + response.copy_to(tempfile) + tempfile.close + @config.logger.info "Temp file written to #{tempfile.path}, please copy the file to a proper folder "\ + "with e.g. `FileUtils.cp(tempfile.path, '/new/file/path')` otherwise the temp file "\ + "will be deleted automatically with GC. It's also recommended to delete the temp file "\ + "explicitly with `tempfile.delete`" + + tempfile + end + end + + def session + return @session if defined?(@session) + + session = HTTPX.with( + ssl: @config.ssl, + timeout: ({ request_timeout: @config.timeout } if @config.timeout && @config.timeout.positive?), + origin: "#{@config.scheme}://#{@config.host}", + base_path: (@config.base_path.sub(/\/+\z/, '') if @config.base_path) + ) + + if @config.proxy + session = session.plugin(:proxy, proxy: @config.proxy) + end + + if @config.username && @config.password + session = session.plugin(:basic_auth).basic_auth(@config.username, @config.password) + end + + session = @config.configure(session) + + @session = session + + end diff --git a/config/clients/ruby/template/api_client_typhoeus_partial.mustache b/config/clients/ruby/template/api_client_typhoeus_partial.mustache new file mode 100644 index 00000000..f55f9804 --- /dev/null +++ b/config/clients/ruby/template/api_client_typhoeus_partial.mustache @@ -0,0 +1,160 @@ + # Call an API with given options. + # + # @return [Array<(Object, Integer, Hash)>] an array of 3 elements: + # the data deserialized from response body (may be a Tempfile or nil), response status code and response headers. + def call_api(http_method, path, opts = {}) + request = build_request(http_method, path, opts) + tempfile = nil + (download_file(request) { tempfile = _1 }) if opts[:return_type] == 'File' + response = request.run + + if @config.debugging + @config.logger.debug "HTTP response body ~BEGIN~\n#{response.body}\n~END~\n" + end + + unless response.success? + if response.timed_out? + fail ApiError.new('Connection timed out') + elsif response.code == 0 + # Errors from libcurl will be made visible here + fail ApiError.new(:code => 0, + :message => response.return_message) + else + fail ApiError.new(:code => response.code, + :response_headers => response.headers, + :response_body => response.body), + response.status_message + end + end + + if opts[:return_type] == 'File' + data = tempfile + elsif opts[:return_type] + data = deserialize(response, opts[:return_type]) + else + data = nil + end + return data, response.code, response.headers + end + + # Builds the HTTP request + # + # @param [String] http_method HTTP method/verb (e.g. POST) + # @param [String] path URL path (e.g. /account/new) + # @option opts [Hash] :header_params Header parameters + # @option opts [Hash] :query_params Query parameters + # @option opts [Hash] :form_params Query parameters + # @option opts [Object] :body HTTP body (JSON/XML) + # @return [Typhoeus::Request] A Typhoeus Request + def build_request(http_method, path, opts = {}) + url = build_request_url(path, opts) + http_method = http_method.to_sym.downcase + + header_params = @default_headers.merge(opts[:header_params] || {}) + query_params = opts[:query_params] || {} + form_params = opts[:form_params] || {} + follow_location = opts[:follow_location] || true + + {{#hasAuthMethods}} + update_params_for_auth! header_params, query_params, opts[:auth_names] + {{/hasAuthMethods}} + + # set ssl_verifyhosts option based on @config.verify_ssl_host (true/false) + _verify_ssl_host = @config.verify_ssl_host ? 2 : 0 + + req_opts = { + :method => http_method, + :headers => header_params, + :params => query_params, + :params_encoding => @config.params_encoding, + :timeout => @config.timeout, + :ssl_verifypeer => @config.verify_ssl, + :ssl_verifyhost => _verify_ssl_host, + :sslcert => @config.cert_file, + :sslkey => @config.key_file, + :verbose => @config.debugging, + :followlocation => follow_location + } + + # set custom cert, if provided + req_opts[:cainfo] = @config.ssl_ca_cert if @config.ssl_ca_cert + + if [:post, :patch, :put, :delete].include?(http_method) + req_body = build_request_body(header_params, form_params, opts[:body]) + req_opts.update :body => req_body + if @config.debugging + @config.logger.debug "HTTP request body param ~BEGIN~\n#{req_body}\n~END~\n" + end + end + + Typhoeus::Request.new(url, req_opts) + end + + # Builds the HTTP request body + # + # @param [Hash] header_params Header parameters + # @param [Hash] form_params Query parameters + # @param [Object] body HTTP body (JSON/XML) + # @return [String] HTTP body data in the form of string + def build_request_body(header_params, form_params, body) + # http form + if header_params['Content-Type'] == 'application/x-www-form-urlencoded' || + header_params['Content-Type'] == 'multipart/form-data' + data = {} + form_params.each do |key, value| + case value + when ::File, ::Array, nil + # let typhoeus handle File, Array and nil parameters + data[key] = value + else + data[key] = value.to_s + end + end + elsif body + data = body.is_a?(String) ? body : body.to_json + else + data = nil + end + data + end + + # Save response body into a file in (the defined) temporary folder, using the filename + # from the "Content-Disposition" header if provided, otherwise a random filename. + # The response body is written to the file in chunks in order to handle files which + # size is larger than maximum Ruby String or even larger than the maximum memory a Ruby + # process can use. + # + # @see Configuration#temp_folder_path + # + # @return [Tempfile] the tempfile generated + def download_file(request) + tempfile = nil + encoding = nil + request.on_headers do |response| + content_disposition = response.headers['Content-Disposition'] + if content_disposition && content_disposition =~ /filename=/i + filename = content_disposition[/filename=['"]?([^'"\s]+)['"]?/, 1] + prefix = sanitize_filename(filename) + else + prefix = 'download-' + end + prefix = prefix + '-' unless prefix.end_with?('-') + encoding = response.body.encoding + tempfile = Tempfile.open(prefix, @config.temp_folder_path, encoding: encoding) + end + request.on_body do |chunk| + chunk.force_encoding(encoding) + tempfile.write(chunk) + end + request.on_complete do + if !tempfile + fail ApiError.new("Failed to create the tempfile based on the HTTP response from the server: #{request.inspect}") + end + tempfile.close + @config.logger.info "Temp file written to #{tempfile.path}, please copy the file to a proper folder "\ + "with e.g. `FileUtils.cp(tempfile.path, '/new/file/path')` otherwise the temp file "\ + "will be deleted automatically with GC. It's also recommended to delete the temp file "\ + "explicitly with `tempfile.delete`" + yield tempfile if block_given? + end + end diff --git a/config/clients/ruby/template/api_doc.mustache b/config/clients/ruby/template/api_doc.mustache new file mode 100644 index 00000000..ab2e666e --- /dev/null +++ b/config/clients/ruby/template/api_doc.mustache @@ -0,0 +1,132 @@ +# {{moduleName}}::{{classname}}{{#description}} + +{{.}}{{/description}} + +All URIs are relative to *{{basePath}}* + +| Method | HTTP request | Description | +| ------ | ------------ | ----------- | +{{#operations}} +{{#operation}} +| [**{{operationId}}**]({{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{summary}} | +{{/operation}} +{{/operations}} + +{{#operations}} +{{#operation}} + +## {{operationId}} + +> {{#returnType}}{{#returnTypeIsPrimitive}}{{returnType}}{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}<{{{returnType}}}>{{/returnTypeIsPrimitive}} {{/returnType}}{{operationId}}{{#hasParams}}({{^vendorExtensions.x-group-parameters}}{{#requiredParams}}{{{paramName}}}{{^-last}}, {{/-last}}{{/requiredParams}}{{#optionalParams}}{{#-last}}{{#hasRequiredParams}}, {{/hasRequiredParams}}opts{{/-last}}{{/optionalParams}}{{/vendorExtensions.x-group-parameters}}{{#vendorExtensions.x-group-parameters}}opts{{/vendorExtensions.x-group-parameters}}){{/hasParams}} + +{{{summary}}}{{#notes}} + +{{{.}}}{{/notes}} + +### Examples + +```ruby +require 'time' +require '{{{gemName}}}' +{{#hasAuthMethods}} +# setup authorization +{{{moduleName}}}.configure do |config|{{#authMethods}}{{#isBasic}}{{#isBasicBasic}} + # Configure HTTP basic authorization: {{{name}}} + config.username = 'YOUR USERNAME' + config.password = 'YOUR PASSWORD'{{/isBasicBasic}}{{#isBasicBearer}} + # Configure Bearer authorization{{#bearerFormat}} ({{{.}}}){{/bearerFormat}}: {{{name}}} + config.access_token = 'YOUR_BEARER_TOKEN'{{/isBasicBearer}}{{/isBasic}}{{#isApiKey}} + # Configure API key authorization: {{{name}}} + config.api_key['{{{keyParamName}}}'] = 'YOUR API KEY' + # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil) + # config.api_key_prefix['{{{keyParamName}}}'] = 'Bearer'{{/isApiKey}}{{#isOAuth}} + # Configure OAuth2 access token for authorization: {{{name}}} + config.access_token = 'YOUR ACCESS TOKEN'{{/isOAuth}} +{{/authMethods}}end +{{/hasAuthMethods}} + +api_instance = {{{moduleName}}}::{{{classname}}}.new +{{^vendorExtensions.x-group-parameters}} +{{#requiredParams}} +{{{paramName}}} = {{{vendorExtensions.x-ruby-example}}} # {{{dataType}}} | {{{description}}} +{{/requiredParams}} +{{#optionalParams}} +{{#-first}} +opts = { +{{/-first}} + {{{paramName}}}: {{{vendorExtensions.x-ruby-example}}}{{^-last}},{{/-last}} # {{{dataType}}} | {{{description}}} +{{#-last}} +} +{{/-last}} +{{/optionalParams}} +{{/vendorExtensions.x-group-parameters}} +{{#vendorExtensions.x-group-parameters}} +{{#hasParams}} +opts = { +{{#requiredParams}} + {{{paramName}}}: {{{vendorExtensions.x-ruby-example}}}, # {{{dataType}}} | {{{description}}} (required) +{{/requiredParams}} +{{#optionalParams}} + {{{paramName}}}: {{{vendorExtensions.x-ruby-example}}}, # {{{dataType}}} | {{{description}}} +{{/optionalParams}} +} +{{/hasParams}} +{{/vendorExtensions.x-group-parameters}} + +begin + {{#summary}}# {{{.}}}{{/summary}} + {{#returnType}}result = {{/returnType}}api_instance.{{{operationId}}}{{#hasParams}}({{^vendorExtensions.x-group-parameters}}{{#requiredParams}}{{{paramName}}}{{^-last}}, {{/-last}}{{/requiredParams}}{{#optionalParams}}{{#-last}}{{#hasRequiredParams}}, {{/hasRequiredParams}}opts{{/-last}}{{/optionalParams}}{{/vendorExtensions.x-group-parameters}}{{#vendorExtensions.x-group-parameters}}opts{{/vendorExtensions.x-group-parameters}}){{/hasParams}} + {{#returnType}} + p result + {{/returnType}} +rescue {{{moduleName}}}::ApiError => e + puts "Error when calling {{classname}}->{{{operationId}}}: #{e}" +end +``` + +#### Using the {{operationId}}_with_http_info variant + +This returns an Array which contains the response data{{^returnType}} (`nil` in this case){{/returnType}}, status code and headers. + +> {{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}nil{{/returnType}}, Integer, Hash)> {{operationId}}_with_http_info{{#hasParams}}({{^vendorExtensions.x-group-parameters}}{{#requiredParams}}{{{paramName}}}{{^-last}}, {{/-last}}{{/requiredParams}}{{#optionalParams}}{{#-last}}{{#hasRequiredParams}}, {{/hasRequiredParams}}opts{{/-last}}{{/optionalParams}}{{/vendorExtensions.x-group-parameters}}{{#vendorExtensions.x-group-parameters}}opts{{/vendorExtensions.x-group-parameters}}){{/hasParams}} + +```ruby +begin + {{#summary}}# {{{.}}}{{/summary}} + data, status_code, headers = api_instance.{{{operationId}}}_with_http_info{{#hasParams}}({{^vendorExtensions.x-group-parameters}}{{#requiredParams}}{{{paramName}}}{{^-last}}, {{/-last}}{{/requiredParams}}{{#optionalParams}}{{#-last}}{{#hasRequiredParams}}, {{/hasRequiredParams}}opts{{/-last}}{{/optionalParams}}{{/vendorExtensions.x-group-parameters}}{{#vendorExtensions.x-group-parameters}}opts{{/vendorExtensions.x-group-parameters}}){{/hasParams}} + p status_code # => 2xx + p headers # => { ... } + p data # => {{#returnType}}{{#returnTypeIsPrimitive}}{{returnType}}{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}<{{{returnType}}}>{{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}nil{{/returnType}} +rescue {{{moduleName}}}::ApiError => e + puts "Error when calling {{classname}}->{{{operationId}}}_with_http_info: #{e}" +end +``` + +### Parameters + +{{^allParams}} +This endpoint does not need any parameter. +{{/allParams}} +{{#allParams}} +{{#-first}} +| Name | Type | Description | Notes | +| ---- | ---- | ----------- | ----- | +{{/-first}} +| **{{paramName}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{#isFile}}**{{dataType}}**{{/isFile}}{{^isFile}}[**{{dataType}}**]({{baseType}}.md){{/isFile}}{{/isPrimitiveType}} | {{description}} | {{^required}}[optional]{{/required}}{{#defaultValue}}[default to {{.}}]{{/defaultValue}} | +{{/allParams}} + +### Return type + +{{#returnType}}{{#returnTypeIsPrimitive}}**{{returnType}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}[**{{returnType}}**]({{returnBaseType}}.md){{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}nil (empty response body){{/returnType}} + +### Authorization + +{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{name}}](../README.md#{{name}}){{^-last}}, {{/-last}}{{/authMethods}} + +### HTTP request headers + +- **Content-Type**: {{#consumes}}{{{mediaType}}}{{^-last}}, {{/-last}}{{/consumes}}{{^consumes}}Not defined{{/consumes}} +- **Accept**: {{#produces}}{{{mediaType}}}{{^-last}}, {{/-last}}{{/produces}}{{^produces}}Not defined{{/produces}} + +{{/operation}} +{{/operations}} diff --git a/config/clients/ruby/template/api_error.mustache b/config/clients/ruby/template/api_error.mustache new file mode 100644 index 00000000..38ee669a --- /dev/null +++ b/config/clients/ruby/template/api_error.mustache @@ -0,0 +1,51 @@ +=begin +{{> api_info}} + +=end + +module {{moduleName}} + class ApiError < StandardError + attr_reader :code, :response_headers, :response_body + + # Usage examples: + # ApiError.new + # ApiError.new("message") + # ApiError.new(:code => 500, :response_headers => {}, :response_body => "") + # ApiError.new(:code => 404, :message => "Not Found") + def initialize(arg = nil) + if arg.is_a? Hash + if arg.key?(:message) || arg.key?('message') + super(arg[:message] || arg['message']) + else + super arg + end + + arg.each do |k, v| + instance_variable_set "@#{k}", v + end + else + super arg + @message = arg + end + end + + # Override to_s to display a friendly error message + def to_s + message + end + + def message + if @message.nil? + msg = "Error message: the server returns an error" + else + msg = @message + end + + msg += "\nHTTP status code: #{code}" if code + msg += "\nResponse headers: #{response_headers}" if response_headers + msg += "\nResponse body: #{response_body}" if response_body + + msg + end + end +end diff --git a/config/clients/ruby/template/api_info.mustache b/config/clients/ruby/template/api_info.mustache new file mode 100644 index 00000000..be6dda91 --- /dev/null +++ b/config/clients/ruby/template/api_info.mustache @@ -0,0 +1,12 @@ +{{#appName}} +#{{{.}}} + +{{/appName}} +{{#appDescription}} +#{{{.}}} + +{{/appDescription}} +{{#version}}The version of the OpenAPI document: {{.}}{{/version}} +{{#infoEmail}}Contact: {{{.}}}{{/infoEmail}} +Generated by: https://openapi-generator.tech +Generator version: {{{generatorVersion}}} diff --git a/config/clients/ruby/template/api_model_base.mustache b/config/clients/ruby/template/api_model_base.mustache new file mode 100644 index 00000000..1a8efff7 --- /dev/null +++ b/config/clients/ruby/template/api_model_base.mustache @@ -0,0 +1,81 @@ +=begin +{{> api_info}} + +=end + +module {{moduleName}} + class ApiModelBase + # Deserializes the data based on type + # @param string type Data type + # @param string value Value to be deserialized + # @return [Object] Deserialized data + def self._deserialize(type, value) + case type.to_sym + when :Time + Time.parse(value) + when :Date + Date.parse(value) + when :String + value.to_s + when :Integer + value.to_i + when :Float + value.to_f + when :Boolean + if value.to_s =~ /\A(true|t|yes|y|1)\z/i + true + else + false + end + when :Object + # generic object (usually a Hash), return directly + value + when /\AArray<(?.+)>\z/ + inner_type = Regexp.last_match[:inner_type] + value.map { |v| _deserialize(inner_type, v) } + when /\AHash<(?.+?), (?.+)>\z/ + k_type = Regexp.last_match[:k_type] + v_type = Regexp.last_match[:v_type] + {}.tap do |hash| + value.each do |k, v| + hash[_deserialize(k_type, k)] = _deserialize(v_type, v) + end + end + else # model + # models (e.g. Pet) or oneOf + klass = {{moduleName}}.const_get(type) + klass.respond_to?(:openapi_any_of) || klass.respond_to?(:openapi_one_of) ? klass.build(value) : klass.build_from_hash(value) + end + end + + # Returns the string representation of the object + # @return [String] String presentation of the object + def to_s + to_hash.to_s + end + + # to_body is an alias to to_hash (backward compatibility) + # @return [Hash] Returns the object in the form of hash + def to_body + to_hash + end + + # Outputs non-array value in the form of hash + # For object, use to_hash. Otherwise, just return the value + # @param [Object] value Any valid value + # @return [Hash] Returns the value in the form of hash + def _to_hash(value) + if value.is_a?(Array) + value.compact.map { |v| _to_hash(v) } + elsif value.is_a?(Hash) + {}.tap do |hash| + value.each { |k, v| hash[k] = _to_hash(v) } + end + elsif value.respond_to? :to_hash + value.to_hash + else + value + end + end + end +end diff --git a/config/clients/ruby/template/api_test.mustache b/config/clients/ruby/template/api_test.mustache new file mode 100644 index 00000000..90264f76 --- /dev/null +++ b/config/clients/ruby/template/api_test.mustache @@ -0,0 +1,48 @@ +=begin +{{> api_info}} + +=end + +require 'spec_helper' +require 'json' + +# Unit tests for {{moduleName}}::{{classname}} +# Automatically generated by openapi-generator (https://openapi-generator.tech) +# Please update as you see appropriate +{{#operations}}describe '{{classname}}' do + before do + # run before each test + @api_instance = {{moduleName}}::{{classname}}.new + end + + after do + # run after each test + end + + describe 'test an instance of {{classname}}' do + it 'should create an instance of {{classname}}' do + expect(@api_instance).to be_instance_of({{moduleName}}::{{classname}}) + end + end + +{{#operation}} + # unit tests for {{operationId}} + {{#summary}} + # {{.}} + {{/summary}} + {{#notes}} + # {{.}} + {{/notes}} +{{#allParams}}{{#required}} # @param {{paramName}} {{description}} +{{/required}}{{/allParams}} # @param [Hash] opts the optional parameters +{{#allParams}}{{^required}} # @option opts [{{{dataType}}}] :{{paramName}} {{description}} +{{/required}}{{/allParams}} # @return [{{{returnType}}}{{^returnType}}nil{{/returnType}}] + describe '{{operationId}} test' do + it 'should work' do + # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/ + end + end + +{{/operation}} +end +{{/operations}} diff --git a/config/clients/ruby/template/base_object.mustache b/config/clients/ruby/template/base_object.mustache new file mode 100644 index 00000000..d752c497 --- /dev/null +++ b/config/clients/ruby/template/base_object.mustache @@ -0,0 +1,41 @@ + # Builds the object from hash + # @param [Hash] attributes Model attributes in the form of hash + # @return [Object] Returns the model itself + def self.build_from_hash(attributes) + return nil unless attributes.is_a?(Hash) + {{#parent}} + super(attributes) + {{/parent}} + attributes = attributes.transform_keys(&:to_sym) + transformed_hash = {} + openapi_types.each_pair do |key, type| + if attributes.key?(attribute_map[key]) && attributes[attribute_map[key]].nil? + transformed_hash["#{key}"] = nil + elsif type =~ /\AArray<(.*)>/i + # check to ensure the input is an array given that the attribute + # is documented as an array but the input is not + if attributes[attribute_map[key]].is_a?(Array) + transformed_hash["#{key}"] = attributes[attribute_map[key]].map { |v| _deserialize($1, v) } + end + elsif !attributes[attribute_map[key]].nil? + transformed_hash["#{key}"] = _deserialize(type, attributes[attribute_map[key]]) + end + end + new(transformed_hash) + end + + # Returns the object in the form of hash + # @return [Hash] Returns the object in the form of hash + def to_hash + hash = {{^parent}}{}{{/parent}}{{#parent}}super{{/parent}} + self.class.attribute_map.each_pair do |attr, param| + value = self.send(attr) + if value.nil? + is_nullable = self.class.openapi_nullable.include?(attr) + next if !is_nullable || (is_nullable && !instance_variable_defined?(:"@#{attr}")) + end + + hash[param] = _to_hash(value) + end + hash + end diff --git a/config/clients/ruby/template/configuration.mustache b/config/clients/ruby/template/configuration.mustache new file mode 100644 index 00000000..463440ca --- /dev/null +++ b/config/clients/ruby/template/configuration.mustache @@ -0,0 +1,495 @@ +=begin +{{> api_info}} + +=end + +module {{moduleName}} + class Configuration + # Defines url scheme + attr_accessor :scheme + + # Defines url host + attr_accessor :host + + # Defines url base path + attr_accessor :base_path + + # Define server configuration index + attr_accessor :server_index + + # Define server operation configuration index + attr_accessor :server_operation_index + + # Default server variables + attr_accessor :server_variables + + # Default server operation variables + attr_accessor :server_operation_variables + + # Defines API keys used with API Key authentications. + # + # @return [Hash] key: parameter name, value: parameter value (API key) + # + # @example parameter name is "api_key", API key is "xxx" (e.g. "api_key=xxx" in query string) + # config.api_key['api_key'] = 'xxx' + attr_accessor :api_key + + # Defines API key prefixes used with API Key authentications. + # + # @return [Hash] key: parameter name, value: API key prefix + # + # @example parameter name is "Authorization", API key prefix is "Token" (e.g. "Authorization: Token xxx" in headers) + # config.api_key_prefix['api_key'] = 'Token' + attr_accessor :api_key_prefix + + # Defines the username used with HTTP basic authentication. + # + # @return [String] + attr_accessor :username + + # Defines the password used with HTTP basic authentication. + # + # @return [String] + attr_accessor :password + + # Defines the access token (Bearer) used with OAuth2. + attr_accessor :access_token + + # Defines a Proc used to fetch or refresh access tokens (Bearer) used with OAuth2. + # Overrides the access_token if set + # @return [Proc] + attr_accessor :access_token_getter + + # Set this to return data as binary instead of downloading a temp file. When enabled (set to true) + # HTTP responses with return type `File` will be returned as a stream of binary data. + # Default to false. + attr_accessor :return_binary_data + + # Set this to enable/disable debugging. When enabled (set to true), HTTP request/response + # details will be logged with `logger.debug` (see the `logger` attribute). + # Default to false. + # + # @return [true, false] + attr_accessor :debugging + + # Set this to ignore operation servers for the API client. This is useful when you need to + # send requests to a different server than the one specified in the OpenAPI document. + # Will default to the base url defined in the spec but can be overridden by setting + # `scheme`, `host`, `base_path` directly. + # Default to false. + # @return [true, false] + attr_accessor :ignore_operation_servers + + # Defines the logger used for debugging. + # Default to `Rails.logger` (when in Rails) or logging to STDOUT. + # + # @return [#debug] + attr_accessor :logger + + # Defines the temporary folder to store downloaded files + # (for API endpoints that have file response). + # Default to use `Tempfile`. + # + # @return [String] + attr_accessor :temp_folder_path + + # The time limit for HTTP request in seconds. + # Default to 0 (never times out). + attr_accessor :timeout + + # Set this to false to skip client side validation in the operation. + # Default to true. + # @return [true, false] + attr_accessor :client_side_validation + +{{#isTyphoeus}} +{{> configuration_typhoeus_partial}} + +{{/isTyphoeus}} +{{#isFaraday}} +{{> configuration_faraday_partial}} + +{{/isFaraday}} +{{#isHttpx}} +{{> configuration_httpx_partial}} + +{{/isHttpx}} + + attr_accessor :inject_format + + attr_accessor :force_ending_format + + def initialize + @scheme = '{{scheme}}' + @host = '{{host}}{{#port}}:{{{.}}}{{/port}}' + @base_path = '{{contextPath}}' + @server_index = nil + @server_operation_index = {} + @server_variables = {} + @server_operation_variables = {} + @api_key = {} + @api_key_prefix = {} + @client_side_validation = true + {{#isFaraday}} + @ssl_verify = true + @ssl_verify_mode = nil + @ssl_ca_file = nil + @ssl_client_cert = nil + @ssl_client_key = nil + @middlewares = Hash.new { |h, k| h[k] = [] } + @configure_connection_blocks = [] + @timeout = 60 + # return data as binary instead of file + @return_binary_data = false + @params_encoder = nil + {{/isFaraday}} + {{#isTyphoeus}} + @verify_ssl = true + @verify_ssl_host = true + @cert_file = nil + @key_file = nil + @timeout = 0 + @params_encoding = nil + {{/isTyphoeus}} + {{#isHttpx}} + @ssl = nil + @proxy = nil + @timeout = 60 + @configure_session_blocks = [] + {{/isHttpx}} + @debugging = false + @ignore_operation_servers = false + @inject_format = false + @force_ending_format = false + @logger = defined?(Rails) ? Rails.logger : Logger.new(STDOUT) + + yield(self) if block_given? + end + + # The default Configuration object. + def self.default + @@default ||= Configuration.new + end + + def configure + yield(self) if block_given? + end + + def scheme=(scheme) + # remove :// from scheme + @scheme = scheme.sub(/:\/\//, '') + end + + def host=(host) + # remove http(s):// and anything after a slash + @host = host.sub(/https?:\/\//, '').split('/').first + end + + def base_path=(base_path) + # Add leading and trailing slashes to base_path + @base_path = "/#{base_path}".gsub(/\/+/, '/') + @base_path = '' if @base_path == '/' + end + + # Returns base URL for specified operation based on server settings + def base_url(operation = nil) + return "#{scheme}://#{[host, base_path].join('/').gsub(/\/+/, '/')}".sub(/\/+\z/, '') if ignore_operation_servers + if operation_server_settings.key?(operation) then + index = server_operation_index.fetch(operation, server_index) + server_url(index.nil? ? 0 : index, server_operation_variables.fetch(operation, server_variables), operation_server_settings[operation]) + else + server_index.nil? ? "#{scheme}://#{[host, base_path].join('/').gsub(/\/+/, '/')}".sub(/\/+\z/, '') : server_url(server_index, server_variables, nil) + end + end + + # Gets API key (with prefix if set). + # @param [String] param_name the parameter name of API key auth + def api_key_with_prefix(param_name, param_alias = nil) + key = @api_key[param_name] + key = @api_key.fetch(param_alias, key) unless param_alias.nil? + if @api_key_prefix[param_name] + "#{@api_key_prefix[param_name]} #{key}" + else + key + end + end + + # Gets access_token using access_token_getter or uses the static access_token + def access_token_with_refresh + return access_token if access_token_getter.nil? + access_token_getter.call + end + + # Gets Basic Auth token string + def basic_auth_token + 'Basic ' + ["#{username}:#{password}"].pack('m').delete("\r\n") + end + + # Returns Auth Settings hash for api client. + def auth_settings + { +{{#authMethods}} +{{#isApiKey}} + '{{name}}' => + { + type: 'api_key', + in: {{#isKeyInHeader}}'header'{{/isKeyInHeader}}{{#isKeyInQuery}}'query'{{/isKeyInQuery}}, + key: '{{keyParamName}}', + value: api_key_with_prefix('{{keyParamName}}'{{#vendorExtensions.x-auth-id-alias}}, '{{.}}'{{/vendorExtensions.x-auth-id-alias}}) + }, +{{/isApiKey}} +{{#isBasic}} +{{#isBasicBasic}} + '{{name}}' => + { + type: 'basic', + in: 'header', + key: 'Authorization', + value: basic_auth_token + }, +{{/isBasicBasic}} +{{#isBasicBearer}} + '{{name}}' => + { + type: 'bearer', + in: 'header', + {{#bearerFormat}} + format: '{{{.}}}', + {{/bearerFormat}} + key: 'Authorization', + value: "Bearer #{access_token_with_refresh}" + }, +{{/isBasicBearer}} +{{/isBasic}} +{{#isOAuth}} + '{{name}}' => + { + type: 'oauth2', + in: 'header', + key: 'Authorization', + value: "Bearer #{access_token_with_refresh}" + }, +{{/isOAuth}} +{{/authMethods}} + } + end + + # Returns an array of Server setting + def server_settings + [ + {{#servers}} + { + url: "{{{url}}}", + description: "{{{description}}}{{^description}}No description provided{{/description}}", + {{#variables}} + {{#-first}} + variables: { + {{/-first}} + {{{name}}}: { + description: "{{{description}}}{{^description}}No description provided{{/description}}", + default_value: "{{{defaultValue}}}", + {{#enumValues}} + {{#-first}} + enum_values: [ + {{/-first}} + "{{{.}}}"{{^-last}},{{/-last}} + {{#-last}} + ] + {{/-last}} + {{/enumValues}} + }{{^-last}},{{/-last}} + {{#-last}} + } + {{/-last}} + {{/variables}} + }{{^-last}},{{/-last}} + {{/servers}} + ] + end + + def operation_server_settings + { + {{#apiInfo}} + {{#apis}} + {{#operations}} + {{#operation}} + {{#servers}} + {{#-first}} + "{{{classname}}}.{{{nickname}}}": [ + {{/-first}} + { + url: "{{{url}}}", + description: "{{{description}}}{{^description}}No description provided{{/description}}", + {{#variables}} + {{#-first}} + variables: { + {{/-first}} + {{{name}}}: { + description: "{{{description}}}{{^description}}No description provided{{/description}}", + default_value: "{{{defaultValue}}}", + {{#enumValues}} + {{#-first}} + enum_values: [ + {{/-first}} + "{{{.}}}"{{^-last}},{{/-last}} + {{#-last}} + ] + {{/-last}} + {{/enumValues}} + }{{^-last}},{{/-last}} + {{#-last}} + } + {{/-last}} + {{/variables}} + }{{^-last}},{{/-last}} + {{#-last}} + ], + {{/-last}} + {{/servers}} + {{/operation}} + {{/operations}} + {{/apis}} + {{/apiInfo}} + } + end + + # Returns URL based on server settings + # + # @param index array index of the server settings + # @param variables hash of variable and the corresponding value + def server_url(index, variables = {}, servers = nil) + servers = server_settings if servers == nil + + # check array index out of bound + if (index.nil? || index < 0 || index >= servers.size) + fail ArgumentError, "Invalid index #{index} when selecting the server. Must not be nil and must be less than #{servers.size}" + end + + server = servers[index] + url = server[:url] + + return url unless server.key? :variables + + # go through variable and assign a value + server[:variables].each do |name, variable| + if variables.key?(name) + if (!server[:variables][name].key?(:enum_values) || server[:variables][name][:enum_values].include?(variables[name])) + url.gsub! "{" + name.to_s + "}", variables[name] + else + fail ArgumentError, "The variable `#{name}` in the server URL has invalid value #{variables[name]}. Must be #{server[:variables][name][:enum_values]}." + end + else + # use default value + url.gsub! "{" + name.to_s + "}", server[:variables][name][:default_value] + end + end + + url + end + + {{#isFaraday}} + # Configure Faraday connection directly. + # + # ``` + # c.configure_faraday_connection do |conn| + # conn.use Faraday::HttpCache, shared_cache: false, logger: logger + # conn.response :logger, nil, headers: true, bodies: true, log_level: :debug do |logger| + # logger.filter(/(Authorization: )(.*)/, '\1[REDACTED]') + # end + # end + # + # c.configure_faraday_connection do |conn| + # conn.adapter :typhoeus + # end + # ``` + # + # @param block [Proc] `#call`able object that takes one arg, the connection + def configure_faraday_connection(&block) + @configure_connection_blocks << block + end + + def configure_connection(conn) + @configure_connection_blocks.each do |block| + block.call(conn) + end + end + + # Adds middleware to the stack + def use(*middleware) + set_faraday_middleware(:use, *middleware) + end + + # Adds request middleware to the stack + def request(*middleware) + set_faraday_middleware(:request, *middleware) + end + + # Adds response middleware to the stack + def response(*middleware) + set_faraday_middleware(:response, *middleware) + end + + # Adds Faraday middleware setting information to the stack + # + # @example Use the `set_faraday_middleware` method to set middleware information + # config.set_faraday_middleware(:request, :retry, max: 3, methods: [:get, :post], retry_statuses: [503]) + # config.set_faraday_middleware(:response, :logger, nil, { bodies: true, log_level: :debug }) + # config.set_faraday_middleware(:use, Faraday::HttpCache, store: Rails.cache, shared_cache: false) + # config.set_faraday_middleware(:insert, 0, FaradayMiddleware::FollowRedirects, { standards_compliant: true, limit: 1 }) + # config.set_faraday_middleware(:swap, 0, Faraday::Response::Logger) + # config.set_faraday_middleware(:delete, Faraday::Multipart::Middleware) + # + # @see https://github.com/lostisland/faraday/blob/v2.3.0/lib/faraday/rack_builder.rb#L92-L143 + def set_faraday_middleware(operation, key, *args, &block) + unless [:request, :response, :use, :insert, :insert_before, :insert_after, :swap, :delete].include?(operation) + fail ArgumentError, "Invalid faraday middleware operation #{operation}. Must be" \ + " :request, :response, :use, :insert, :insert_before, :insert_after, :swap or :delete." + end + + @middlewares[operation] << [key, args, block] + end + ruby2_keywords(:set_faraday_middleware) if respond_to?(:ruby2_keywords, true) + + # Set up middleware on the connection + def configure_middleware(connection) + return if @middlewares.empty? + + [:request, :response, :use, :insert, :insert_before, :insert_after, :swap].each do |operation| + next unless @middlewares.key?(operation) + + @middlewares[operation].each do |key, args, block| + connection.builder.send(operation, key, *args, &block) + end + end + + if @middlewares.key?(:delete) + @middlewares[:delete].each do |key, _args, _block| + connection.builder.delete(key) + end + end + end + {{/isFaraday}} + + {{#isHttpx}} + # Configure Httpx session directly. + # + # ``` + # c.configure_session do |http| + # http.plugin(:follow_redirects).with(debug: STDOUT, debug_level: 1) + # end + # ``` + # + # @param block [Proc] `#call`able object that takes one arg, the connection + def configure_session(&block) + @configure_session_blocks << block + end + + + def configure(session) + @configure_session_blocks.reduce(session) do |configured_sess, block| + block.call(configured_sess) + end + end + {{/isHttpx}} + end +end diff --git a/config/clients/ruby/template/configuration_faraday_partial.mustache b/config/clients/ruby/template/configuration_faraday_partial.mustache new file mode 100644 index 00000000..6c7466cb --- /dev/null +++ b/config/clients/ruby/template/configuration_faraday_partial.mustache @@ -0,0 +1,40 @@ + ### TLS/SSL setting + # Set this to false to skip verifying SSL certificate when calling API from https server. + # Default to true. + # + # @note Do NOT set it to false in production code, otherwise you would face multiple types of cryptographic attacks. + # + # @return [true, false] + attr_accessor :ssl_verify + + ### TLS/SSL setting + # Any `OpenSSL::SSL::` constant (see https://ruby-doc.org/3.4.1/exts/openssl/OpenSSL.html) + # + # @note Do NOT set it to false in production code, otherwise you would face multiple types of cryptographic attacks. + # + attr_accessor :ssl_verify_mode + + ### TLS/SSL setting + # Set this to customize the certificate file to verify the peer. + # + # @return [String] the path to the certificate file + attr_accessor :ssl_ca_file + + ### TLS/SSL setting + # Client certificate file (for client certificate) + attr_accessor :ssl_client_cert + + ### TLS/SSL setting + # Client private key file (for client certificate) + attr_accessor :ssl_client_key + + ### Proxy setting + # HTTP Proxy settings + attr_accessor :proxy + + # Set this to customize parameters encoder of array parameter. + # Default to nil. Faraday uses NestedParamsEncoder when nil. + # + # @see The params_encoder option of Faraday. Related source code: + # https://github.com/lostisland/faraday/tree/main/lib/faraday/encoders + attr_accessor :params_encoder diff --git a/config/clients/ruby/template/constants.mustache b/config/clients/ruby/template/constants.mustache new file mode 100644 index 00000000..08a0e0e9 --- /dev/null +++ b/config/clients/ruby/template/constants.mustache @@ -0,0 +1,84 @@ +# frozen_string_literal: true + +{{>partial_header}} + +module {{moduleName}} + # Version of the OpenFGA Ruby SDK. + SDK_VERSION = {{moduleName}}::VERSION + + # User agent used in HTTP requests. + USER_AGENT = "{{userAgent}}" + + # Example API domain for documentation/tests. + SAMPLE_BASE_DOMAIN = "{{sampleApiDomain}}" + + # API URL used for tests. + TEST_API_URL = "https://api.#{SAMPLE_BASE_DOMAIN}" + + # API Token Issuer URL used for tests. + TEST_ISSUER_URL = "https://issuer.#{SAMPLE_BASE_DOMAIN}" + + # Default API URL. + DEFAULT_API_URL = "{{defaultApiUrl}}" + + # Retry configuration + + # Maximum allowed number of retries for HTTP requests. + RETRY_MAX_ALLOWED_NUMBER = {{retryMaxAllowedNumber}} + + # Default maximum number of retries for HTTP requests. + DEFAULT_MAX_RETRY = {{defaultMaxRetry}} + + # Default minimum wait time between retries in milliseconds. + DEFAULT_MIN_WAIT_IN_MS = {{defaultMinWaitInMs}} + + # Maximum backoff time in seconds. + MAX_BACKOFF_TIME_IN_SEC = {{maxBackoffTimeInSec}} + + # Maximum allowable duration for retry headers in seconds. + RETRY_HEADER_MAX_ALLOWABLE_DURATION_IN_SEC = {{retryHeaderMaxAllowableDurationInSec}} + + # Standard HTTP header for retry-after. + RETRY_AFTER_HEADER_NAME = "{{retryAfterHeaderName}}" + + # Rate limit reset header name. + RATE_LIMIT_RESET_HEADER_NAME = "{{rateLimitResetHeaderName}}" + + # Alternative rate limit reset header name. + RATE_LIMIT_RESET_ALT_HEADER_NAME = "{{rateLimitResetAltHeaderName}}" + + # Client methods + + # Maximum number of parallel requests for a single method. + CLIENT_MAX_METHOD_PARALLEL_REQUESTS = {{clientMaxMethodParallelRequests}} + + # Maximum batch size for batch requests. + CLIENT_MAX_BATCH_SIZE = {{clientMaxBatchSize}} + + # Header used to identify the client method. + CLIENT_METHOD_HEADER = "{{clientMethodHeader}}" + + # Header used to identify bulk requests. + CLIENT_BULK_REQUEST_ID_HEADER = "{{clientBulkRequestIdHeader}}" + + # Connection options + + # Default timeout for HTTP requests in milliseconds. + DEFAULT_REQUEST_TIMEOUT_IN_MS = {{defaultRequestTimeoutInMs}} + + # Default connection timeout in milliseconds. + DEFAULT_CONNECTION_TIMEOUT_IN_MS = {{defaultConnectionTimeoutInMs}} + + # Token management + + # Buffer time in seconds before token expiry to consider it expired. + TOKEN_EXPIRY_THRESHOLD_BUFFER_IN_SEC = {{tokenExpiryThresholdBufferInSec}} + + # Jitter time in seconds to add randomness to token expiry checks. + TOKEN_EXPIRY_JITTER_IN_SEC = {{tokenExpiryJitterInSec}} + + # FGA Response Headers + + # Response header name for query duration in milliseconds. + QUERY_DURATION_HEADER_NAME = "{{queryDurationHeaderName}}" +end diff --git a/config/clients/ruby/template/gem.mustache b/config/clients/ruby/template/gem.mustache new file mode 100644 index 00000000..22f84a38 --- /dev/null +++ b/config/clients/ruby/template/gem.mustache @@ -0,0 +1,69 @@ +=begin +{{> api_info}} + +=end + +# Common files +require '{{gemName}}/version' +require '{{gemName}}/constants' +require '{{gemName}}/api_client' +require '{{gemName}}/api_error' +require '{{gemName}}/api_model_base' +require '{{gemName}}/configuration' + +require '{{gemName}}/imports' + +# Models +{{^useAutoload}} +{{#models}} +{{#model}} +{{^parent}} +require '{{gemName}}/{{modelPackage}}/{{classFilename}}' +{{/parent}} +{{/model}} +{{/models}} +{{#models}} +{{#model}} +{{#parent}} +require '{{gemName}}/{{modelPackage}}/{{classFilename}}' +{{/parent}} +{{/model}} +{{/models}} +{{/useAutoload}} +{{#useAutoload}} +{{#models}} +{{#model}} +{{moduleName}}.autoload :{{classname}}, '{{gemName}}/{{modelPackage}}/{{classFilename}}' +{{/model}} +{{/models}} +{{/useAutoload}} + +# APIs +{{#apiInfo}} +{{#apis}} +{{^useAutoload}} +require '{{importPath}}' +{{/useAutoload}} +{{#useAutoload}} +{{moduleName}}.autoload :{{classname}}, '{{importPath}}' +{{/useAutoload}} +{{/apis}} +{{/apiInfo}} + +module {{moduleName}} + class << self + # Customize default settings for the SDK using block. + # {{moduleName}}.configure do |config| + # config.username = "xxx" + # config.password = "xxx" + # end + # If no block given, return the default Configuration object. + def configure + if block_given? + yield(Configuration.default) + else + Configuration.default + end + end + end +end diff --git a/config/clients/ruby/template/gemspec.mustache b/config/clients/ruby/template/gemspec.mustache new file mode 100644 index 00000000..407f2af7 --- /dev/null +++ b/config/clients/ruby/template/gemspec.mustache @@ -0,0 +1,42 @@ +# -*- encoding: utf-8 -*- + +=begin +{{> api_info}} + +=end + +$:.push File.expand_path("../lib", __FILE__) +require "{{gemName}}/version" + +Gem::Specification.new do |s| + s.name = "{{gemName}}{{^gemName}}{{{appName}}}{{/gemName}}" + s.version = {{moduleName}}::VERSION + s.platform = Gem::Platform::RUBY + s.authors = ["{{gemAuthor}}{{^gemAuthor}}OpenAPI-Generator{{/gemAuthor}}"] + s.email = ["{{gemAuthorEmail}}{{^gemAuthorEmail}}{{infoEmail}}{{/gemAuthorEmail}}"] + s.homepage = "{{gemHomepage}}{{^gemHomepage}}https://openapi-generator.tech{{/gemHomepage}}" + s.summary = "{{gemSummary}}{{^gemSummary}}{{{appName}}} Ruby Gem{{/gemSummary}}" + s.description = "{{gemDescription}}{{^gemDescription}}{{{appDescription}}}{{^appDescription}}{{{appName}}} Ruby Gem{{/appDescription}}{{/gemDescription}}" + s.license = "{{{gemLicense}}}{{^gemLicense}}Unlicense{{/gemLicense}}" + s.required_ruby_version = "{{{gemRequiredRubyVersion}}}{{^gemRequiredRubyVersion}}>= 2.7{{/gemRequiredRubyVersion}}" + s.metadata = {{{gemMetadata}}}{{^gemMetadata}}{}{{/gemMetadata}} + + {{#isFaraday}} + s.add_runtime_dependency 'faraday', '>= 1.0.1', '< 3.0' + s.add_runtime_dependency 'faraday-multipart' + s.add_runtime_dependency 'marcel' + s.add_runtime_dependency 'concurrent-ruby' + {{/isFaraday}} + {{#isTyphoeus}} + s.add_runtime_dependency 'typhoeus', '~> 1.0', '>= 1.0.1' + {{/isTyphoeus}} + {{#isHttpx}} + s.add_runtime_dependency 'httpx', '~> 1.0', '>= 1.0.0' + {{/isHttpx}} + + s.add_development_dependency 'rspec', '~> 3.6', '>= 3.6.0' + + s.files = `find *`.split("\n").uniq.sort.select { |f| !f.empty? } + s.executables = [] + s.require_paths = ["lib"] +end diff --git a/config/clients/ruby/template/gitignore_custom.mustache b/config/clients/ruby/template/gitignore_custom.mustache new file mode 100644 index 00000000..e69de29b diff --git a/config/clients/ruby/template/model.mustache b/config/clients/ruby/template/model.mustache new file mode 100644 index 00000000..723dba82 --- /dev/null +++ b/config/clients/ruby/template/model.mustache @@ -0,0 +1,38 @@ +=begin +{{> api_info}} + +=end + +require 'date' +require 'time' + +module {{moduleName}} +{{#models}} +{{#model}} +{{#isEnum}} +{{>partial_model_enum_class}} + +{{/isEnum}} +{{^isEnum}} +{{#oneOf}} +{{#-first}} +{{>partial_oneof_module}} + +{{/-first}} +{{/oneOf}} +{{#anyOf}} +{{#-first}} +{{>partial_anyof_module}} + +{{/-first}} +{{/anyOf}} +{{^oneOf}} +{{^anyOf}} +{{>partial_model_generic}} + +{{/anyOf}} +{{/oneOf}} +{{/isEnum}} +{{/model}} +{{/models}} +end diff --git a/config/clients/ruby/template/model_doc.mustache b/config/clients/ruby/template/model_doc.mustache new file mode 100644 index 00000000..6b4fb320 --- /dev/null +++ b/config/clients/ruby/template/model_doc.mustache @@ -0,0 +1,14 @@ +{{#models}} +{{#model}} +{{#oneOf}} +{{#-first}} +{{>partial_oneof_module_doc}} + +{{/-first}} +{{/oneOf}} +{{^oneOf}} +{{>partial_model_generic_doc}} + +{{/oneOf}} +{{/model}} +{{/models}} diff --git a/config/clients/ruby/template/model_test.mustache b/config/clients/ruby/template/model_test.mustache new file mode 100644 index 00000000..468dff37 --- /dev/null +++ b/config/clients/ruby/template/model_test.mustache @@ -0,0 +1,83 @@ +=begin +{{> api_info}} + +=end + +require 'spec_helper' +require 'json' +require 'date' + +# Unit tests for {{moduleName}}::{{classname}} +# Automatically generated by openapi-generator (https://openapi-generator.tech) +# Please update as you see appropriate +{{#models}} +{{#model}} +describe {{moduleName}}::{{classname}} do +{{^oneOf}} +{{^anyOf}} + #let(:instance) { {{moduleName}}::{{classname}}.new } + + describe 'test an instance of {{classname}}' do + it 'should create an instance of {{classname}}' do + # uncomment below to test the instance creation + #expect(instance).to be_instance_of({{moduleName}}::{{classname}}) + end + end + +{{#vars}} + describe 'test attribute "{{{name}}}"' do + it 'should work' do + {{#isEnum}} + # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/ + # validator = Petstore::EnumTest::EnumAttributeValidator.new('{{{dataType}}}', [{{#allowableValues}}{{#enumVars}}{{{value}}}{{^-last}}, {{/-last}}{{/enumVars}}{{/allowableValues}}]) + # validator.allowable_values.each do |value| + # expect { instance.{{name}} = value }.not_to raise_error + # end + {{/isEnum}} + {{^isEnum}} + # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/ + {{/isEnum}} + end + end + +{{/vars}} +{{/anyOf}} +{{/oneOf}} +{{#oneOf}} +{{#-first}} + describe '.openapi_one_of' do + it 'lists the items referenced in the oneOf array' do + expect(described_class.openapi_one_of).to_not be_empty + end + end + + {{#discriminator}} + {{#propertyName}} + describe '.openapi_discriminator_name' do + it 'returns the value of the "discriminator" property' do + expect(described_class.openapi_discriminator_name).to_not be_empty + end + end + + {{/propertyName}} + {{#mappedModels}} + {{#-first}} + describe '.openapi_discriminator_mapping' do + it 'returns the key/values of the "mapping" property' do + expect(described_class.openapi_discriminator_mapping.values.sort).to eq(described_class.openapi_one_of.sort) + end + end + + {{/-first}} + {{/mappedModels}} + {{/discriminator}} + describe '.build' do + it 'returns the correct model' do + # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/ + end + end +{{/-first}} +{{/oneOf}} +end +{{/model}} +{{/models}} diff --git a/config/clients/ruby/template/partial_anyof_module.mustache b/config/clients/ruby/template/partial_anyof_module.mustache new file mode 100644 index 00000000..040a5219 --- /dev/null +++ b/config/clients/ruby/template/partial_anyof_module.mustache @@ -0,0 +1,93 @@ + {{#description}} + # {{{.}}} + {{/description}} + module {{classname}} + class << self + {{#anyOf}} + {{#-first}} + # List of class defined in anyOf (OpenAPI v3) + def openapi_any_of + [ + {{/-first}} + :'{{{.}}}'{{^-last}},{{/-last}} + {{#-last}} + ] + end + + {{/-last}} + {{/anyOf}} + # Builds the object + # @param [Mixed] Data to be matched against the list of anyOf items + # @return [Object] Returns the model or the data itself + def build(data) + # Go through the list of anyOf items and attempt to identify the appropriate one. + # Note: + # - No advanced validation of types in some cases (e.g. "x: { type: string }" will happily match { x: 123 }) + # due to the way the deserialization is made in the base_object template (it just casts without verifying). + # - TODO: scalar values are de facto behaving as if they were nullable. + # - TODO: logging when debugging is set. + openapi_any_of.each do |klass| + begin + next if klass == :AnyType # "nullable: true" + return find_and_cast_into_type(klass, data) + rescue # rescue all errors so we keep iterating even if the current item lookup raises + end + end + + openapi_any_of.include?(:AnyType) ? data : nil + end + + private + + SchemaMismatchError = Class.new(StandardError) + + # Note: 'File' is missing here because in the regular case we get the data _after_ a call to JSON.parse. + def find_and_cast_into_type(klass, data) + return if data.nil? + + case klass.to_s + when 'Boolean' + return data if data.instance_of?(TrueClass) || data.instance_of?(FalseClass) + when 'Float' + return data if data.instance_of?(Float) + when 'Integer' + return data if data.instance_of?(Integer) + when 'Time' + return Time.parse(data) + when 'Date' + return Date.iso8601(data) + when 'String' + return data if data.instance_of?(String) + when 'Object' # "type: object" + return data if data.instance_of?(Hash) + when /\AArray<(?.+)>\z/ # "type: array" + if data.instance_of?(Array) + sub_type = Regexp.last_match[:sub_type] + return data.map { |item| find_and_cast_into_type(sub_type, item) } + end + when /\AHash.+)>\z/ # "type: object" with "additionalProperties: { ... }" + if data.instance_of?(Hash) && data.keys.all? { |k| k.instance_of?(Symbol) || k.instance_of?(String) } + sub_type = Regexp.last_match[:sub_type] + return data.each_with_object({}) { |(k, v), hsh| hsh[k] = find_and_cast_into_type(sub_type, v) } + end + else # model + const = {{moduleName}}.const_get(klass) + if const + if const.respond_to?(:openapi_any_of) # nested anyOf model + model = const.build(data) + return model if model + else + # raise if data contains keys that are not known to the model + raise if const.respond_to?(:acceptable_attributes) && !(data.keys - const.acceptable_attributes).empty? + model = const.build_from_hash(data) + return model if model + end + end + end + + raise # if no match by now, raise + rescue + raise SchemaMismatchError, "#{data} doesn't match the #{klass} type" + end + end + end diff --git a/config/clients/ruby/template/partial_header.mustache b/config/clients/ruby/template/partial_header.mustache new file mode 100644 index 00000000..cafc5f71 --- /dev/null +++ b/config/clients/ruby/template/partial_header.mustache @@ -0,0 +1,19 @@ + {{#packageDescription}} +# {{{packageDescription}}} + {{/packageDescription}} + {{#version}} +# API version: {{{version}}} + {{/version}} + {{#websiteUrl}} +# Website: {{{websiteUrl}}} + {{/websiteUrl}} + {{#docsUrl}} +# Documentation: {{{docsUrl}}} + {{/docsUrl}} + {{#supportInfo}} +# Support: {{{supportInfo}}} + {{/supportInfo}} + {{#licenseId}} +# License: [{{{licenseId}}}](https://{{gitHost}}/{{gitUserId}}/{{gitRepoId}}/blob/main/LICENSE) + {{/licenseId}} +# NOTE: This file was auto generated by OpenAPI Generator (https://openapi-generator.tech). DO NOT EDIT. \ No newline at end of file diff --git a/config/clients/ruby/template/partial_model_enum_class.mustache b/config/clients/ruby/template/partial_model_enum_class.mustache new file mode 100644 index 00000000..d2ddbff1 --- /dev/null +++ b/config/clients/ruby/template/partial_model_enum_class.mustache @@ -0,0 +1,23 @@ + class {{classname}}{{#allowableValues}}{{#enumVars}} + {{{name}}} = {{{value}}}.freeze{{/enumVars}} + +{{/allowableValues}} + def self.all_vars + @all_vars ||= [{{#allowableValues}}{{#enumVars}}{{{name}}}{{^-last}}, {{/-last}}{{/enumVars}}{{/allowableValues}}].freeze + end + + # Builds the enum from string + # @param [String] The enum value in the form of the string + # @return [String] The enum value + def self.build_from_hash(value) + new.build_from_hash(value) + end + + # Builds the enum from string + # @param [String] The enum value in the form of the string + # @return [String] The enum value + def build_from_hash(value) + return value if {{classname}}.all_vars.include?(value) + raise "Invalid ENUM value #{value} for class #{{{classname}}}" + end + end \ No newline at end of file diff --git a/config/clients/ruby/template/partial_model_generic.mustache b/config/clients/ruby/template/partial_model_generic.mustache new file mode 100644 index 00000000..d5ef9e8a --- /dev/null +++ b/config/clients/ruby/template/partial_model_generic.mustache @@ -0,0 +1,400 @@ + {{#description}} + # {{{.}}} + {{/description}} + class {{classname}}{{#parent}} < {{{.}}}{{/parent}}{{^parent}} < ApiModelBase{{/parent}} + {{#vars}} + {{#description}} + # {{{.}}} + {{/description}} + attr_accessor :{{{name}}} + + {{/vars}} +{{#hasEnums}} + class EnumAttributeValidator + attr_reader :datatype + attr_reader :allowable_values + + def initialize(datatype, allowable_values) + @allowable_values = allowable_values.map do |value| + case datatype.to_s + when /Integer/i + value.to_i + when /Float/i + value.to_f + else + value + end + end + end + + def valid?(value) + !value || allowable_values.include?(value) + end + end + +{{/hasEnums}} + # Attribute mapping from ruby-style variable name to JSON key. + def self.attribute_map + { + {{#vars}} + :'{{{name}}}' => :'{{{baseName}}}'{{^-last}},{{/-last}} + {{/vars}} + } + end + + # Returns attribute mapping this model knows about{{#parent}}, including the ones defined in its parent(s){{/parent}} + def self.acceptable_attribute_map + {{^parent}} + attribute_map + {{/parent}} + {{#parent}} + superclass.acceptable_attribute_map.merge(attribute_map) + {{/parent}} + end + + # Returns all the JSON keys this model knows about{{#parent}}, including the ones defined in its parent(s){{/parent}} + def self.acceptable_attributes + acceptable_attribute_map.values + end + + # Attribute type mapping. + def self.openapi_types + { + {{#vars}} + :'{{{name}}}' => :'{{{dataType}}}'{{^-last}},{{/-last}} + {{/vars}} + } + end + + # List of attributes with nullable: true + def self.openapi_nullable + Set.new([ + {{#vars}} + {{#isNullable}} + :'{{{name}}}'{{^-last}},{{/-last}} + {{/isNullable}} + {{/vars}} + ]) + end + + {{#anyOf}} + {{#-first}} + # List of class defined in anyOf (OpenAPI v3) + def self.openapi_any_of + [ + {{/-first}} + :'{{{.}}}'{{^-last}},{{/-last}} + {{#-last}} + ] + end + + {{/-last}} + {{/anyOf}} + {{#allOf}} + {{#-first}} + # List of class defined in allOf (OpenAPI v3) + def self.openapi_all_of + [ + {{/-first}} + :'{{{.}}}'{{^-last}},{{/-last}} + {{#-last}} + ] + end + + {{/-last}} + {{/allOf}} + {{#discriminator}} + {{#propertyName}} + # discriminator's property name in OpenAPI v3 + def self.openapi_discriminator_name + :'{{{.}}}' + end + + {{/propertyName}} + {{/discriminator}} + # Initializes the object + # @param [Hash] attributes Model attributes in the form of hash + def initialize(attributes = {}) + if (!attributes.is_a?(Hash)) + fail ArgumentError, "The input argument (attributes) must be a hash in `{{{moduleName}}}::{{{classname}}}` initialize method" + end + + # check to see if the attribute exists and convert string to symbol for hash key + acceptable_attribute_map = self.class.acceptable_attribute_map + attributes = attributes.each_with_object({}) { |(k, v), h| + if (!acceptable_attribute_map.key?(k.to_sym)) + fail ArgumentError, "`#{k}` is not a valid attribute in `{{{moduleName}}}::{{{classname}}}`. Please check the name to make sure it's valid. List of attributes: " + acceptable_attribute_map.keys.inspect + end + h[k.to_sym] = v + } + {{#parent}} + + # call parent's initialize + super(attributes) + {{/parent}} + {{#vars}} + + if attributes.key?(:'{{{name}}}') + {{#isArray}} + if (value = attributes[:'{{{name}}}']).is_a?(Array) + self.{{{name}}} = value + end + {{/isArray}} + {{#isMap}} + if (value = attributes[:'{{{name}}}']).is_a?(Hash) + self.{{{name}}} = value + end + {{/isMap}} + {{^isContainer}} + self.{{{name}}} = attributes[:'{{{name}}}'] + {{/isContainer}} + {{#defaultValue}} + else + self.{{{name}}} = {{{defaultValue}}} + {{/defaultValue}} + {{^defaultValue}} + {{#required}} + else + self.{{{name}}} = nil + {{/required}} + {{/defaultValue}} + end + {{/vars}} + end + + # Show invalid properties with the reasons. Usually used together with valid? + # @return Array for valid properties with the reasons + def list_invalid_properties + warn '[DEPRECATED] the `list_invalid_properties` method is obsolete' + invalid_properties = {{^parent}}Array.new{{/parent}}{{#parent}}super{{/parent}} + {{#vars}} + {{^isNullable}} + {{#required}} + if @{{{name}}}.nil? + invalid_properties.push('invalid value for "{{{name}}}", {{{name}}} cannot be nil.') + end + + {{/required}} + {{/isNullable}} + {{#hasValidation}} + {{#maxLength}} + if {{^required}}!@{{{name}}}.nil? && {{/required}}@{{{name}}}.to_s.length > {{{maxLength}}} + invalid_properties.push('invalid value for "{{{name}}}", the character length must be smaller than or equal to {{{maxLength}}}.') + end + + {{/maxLength}} + {{#minLength}} + if {{^required}}!@{{{name}}}.nil? && {{/required}}@{{{name}}}.to_s.length < {{{minLength}}} + invalid_properties.push('invalid value for "{{{name}}}", the character length must be greater than or equal to {{{minLength}}}.') + end + + {{/minLength}} + {{#maximum}} + if {{^required}}!@{{{name}}}.nil? && {{/required}}@{{{name}}} >{{#exclusiveMaximum}}={{/exclusiveMaximum}} {{{maximum}}} + invalid_properties.push('invalid value for "{{{name}}}", must be smaller than {{^exclusiveMaximum}}or equal to {{/exclusiveMaximum}}{{{maximum}}}.') + end + + {{/maximum}} + {{#minimum}} + if {{^required}}!@{{{name}}}.nil? && {{/required}}@{{{name}}} <{{#exclusiveMinimum}}={{/exclusiveMinimum}} {{{minimum}}} + invalid_properties.push('invalid value for "{{{name}}}", must be greater than {{^exclusiveMinimum}}or equal to {{/exclusiveMinimum}}{{{minimum}}}.') + end + + {{/minimum}} + {{#pattern}} + pattern = Regexp.new({{{pattern}}}) + if {{^required}}!@{{{name}}}.nil? && {{/required}}@{{{name}}} !~ pattern + invalid_properties.push("invalid value for \"{{{name}}}\", must conform to the pattern #{pattern}.") + end + + {{/pattern}} + {{#maxItems}} + if {{^required}}!@{{{name}}}.nil? && {{/required}}@{{{name}}}.length > {{{maxItems}}} + invalid_properties.push('invalid value for "{{{name}}}", number of items must be less than or equal to {{{maxItems}}}.') + end + + {{/maxItems}} + {{#minItems}} + if {{^required}}!@{{{name}}}.nil? && {{/required}}@{{{name}}}.length < {{{minItems}}} + invalid_properties.push('invalid value for "{{{name}}}", number of items must be greater than or equal to {{{minItems}}}.') + end + + {{/minItems}} + {{/hasValidation}} + {{/vars}} + invalid_properties + end + + # Check to see if the all the properties in the model are valid + # @return true if the model is valid + def valid? + warn '[DEPRECATED] the `valid?` method is obsolete' + {{#vars}} + {{^isNullable}} + {{#required}} + return false if @{{{name}}}.nil? + {{/required}} + {{/isNullable}} + {{#isEnum}} + {{^isContainer}} + {{{name}}}_validator = EnumAttributeValidator.new('{{{dataType}}}', [{{#allowableValues}}{{#enumVars}}{{{value}}}{{^-last}}, {{/-last}}{{/enumVars}}{{/allowableValues}}]) + return false unless {{{name}}}_validator.valid?(@{{{name}}}) + {{/isContainer}} + {{/isEnum}} + {{#hasValidation}} + {{#maxLength}} + return false if {{^required}}!@{{{name}}}.nil? && {{/required}}@{{{name}}}.to_s.length > {{{maxLength}}} + {{/maxLength}} + {{#minLength}} + return false if {{^required}}!@{{{name}}}.nil? && {{/required}}@{{{name}}}.to_s.length < {{{minLength}}} + {{/minLength}} + {{#maximum}} + return false if {{^required}}!@{{{name}}}.nil? && {{/required}}@{{{name}}} >{{#exclusiveMaximum}}={{/exclusiveMaximum}} {{{maximum}}} + {{/maximum}} + {{#minimum}} + return false if {{^required}}!@{{{name}}}.nil? && {{/required}}@{{{name}}} <{{#exclusiveMinimum}}={{/exclusiveMinimum}} {{{minimum}}} + {{/minimum}} + {{#pattern}} + return false if {{^required}}!@{{{name}}}.nil? && {{/required}}@{{{name}}} !~ Regexp.new({{{pattern}}}) + {{/pattern}} + {{#maxItems}} + return false if {{^required}}!@{{{name}}}.nil? && {{/required}}@{{{name}}}.length > {{{maxItems}}} + {{/maxItems}} + {{#minItems}} + return false if {{^required}}!@{{{name}}}.nil? && {{/required}}@{{{name}}}.length < {{{minItems}}} + {{/minItems}} + {{/hasValidation}} + {{/vars}} + {{#anyOf}} + {{#-first}} + _any_of_found = false + self.class.openapi_any_of.each do |_class| + _any_of = {{moduleName}}.const_get(_class).build_from_hash(self.to_hash) + if _any_of.valid? + _any_of_found = true + end + end + + if !_any_of_found + return false + end + + {{/-first}} + {{/anyOf}} + true{{#parent}} && super{{/parent}} + end + + {{#vars}} + {{#isEnum}} + {{^isContainer}} + # Custom attribute writer method checking allowed values (enum). + # @param [Object] {{{name}}} Object to be assigned + def {{{name}}}=({{{name}}}) + validator = EnumAttributeValidator.new('{{{dataType}}}', [{{#allowableValues}}{{#enumVars}}{{{value}}}{{^-last}}, {{/-last}}{{/enumVars}}{{/allowableValues}}]) + unless validator.valid?({{{name}}}) + fail ArgumentError, "invalid value for \"{{{name}}}\", must be one of #{validator.allowable_values}." + end + @{{{name}}} = {{{name}}} + end + + {{/isContainer}} + {{/isEnum}} + {{^isEnum}} + {{#hasValidation}} + # Custom attribute writer method with validation + # @param [Object] {{{name}}} Value to be assigned + def {{{name}}}=({{{name}}}) + {{^isNullable}} + if {{{name}}}.nil? + fail ArgumentError, '{{{name}}} cannot be nil' + end + + {{/isNullable}} + {{#maxLength}} + if {{#isNullable}}!{{{name}}}.nil? && {{/isNullable}}{{{name}}}.to_s.length > {{{maxLength}}} + fail ArgumentError, 'invalid value for "{{{name}}}", the character length must be smaller than or equal to {{{maxLength}}}.' + end + + {{/maxLength}} + {{#minLength}} + if {{#isNullable}}!{{{name}}}.nil? && {{/isNullable}}{{{name}}}.to_s.length < {{{minLength}}} + fail ArgumentError, 'invalid value for "{{{name}}}", the character length must be greater than or equal to {{{minLength}}}.' + end + + {{/minLength}} + {{#maximum}} + if {{#isNullable}}!{{{name}}}.nil? && {{/isNullable}}{{{name}}} >{{#exclusiveMaximum}}={{/exclusiveMaximum}} {{{maximum}}} + fail ArgumentError, 'invalid value for "{{{name}}}", must be smaller than {{^exclusiveMaximum}}or equal to {{/exclusiveMaximum}}{{{maximum}}}.' + end + + {{/maximum}} + {{#minimum}} + if {{#isNullable}}!{{{name}}}.nil? && {{/isNullable}}{{{name}}} <{{#exclusiveMinimum}}={{/exclusiveMinimum}} {{{minimum}}} + fail ArgumentError, 'invalid value for "{{{name}}}", must be greater than {{^exclusiveMinimum}}or equal to {{/exclusiveMinimum}}{{{minimum}}}.' + end + + {{/minimum}} + {{#pattern}} + pattern = Regexp.new({{{pattern}}}) + if {{#isNullable}}!{{{name}}}.nil? && {{/isNullable}}{{{name}}} !~ pattern + fail ArgumentError, "invalid value for \"{{{name}}}\", must conform to the pattern #{pattern}." + end + + {{/pattern}} + {{#maxItems}} + if {{#isNullable}}!{{{name}}}.nil? && {{/isNullable}}{{{name}}}.length > {{{maxItems}}} + fail ArgumentError, 'invalid value for "{{{name}}}", number of items must be less than or equal to {{{maxItems}}}.' + end + + {{/maxItems}} + {{#minItems}} + if {{#isNullable}}!{{{name}}}.nil? && {{/isNullable}}{{{name}}}.length < {{{minItems}}} + fail ArgumentError, 'invalid value for "{{{name}}}", number of items must be greater than or equal to {{{minItems}}}.' + end + + {{/minItems}} + @{{{name}}} = {{{name}}} + end + + {{/hasValidation}} + {{^hasValidation}} + {{^isNullable}} + {{#required}} + # Custom attribute writer method with validation + # @param [Object] {{{name}}} Value to be assigned + def {{{name}}}=({{{name}}}) + if {{{name}}}.nil? + fail ArgumentError, '{{{name}}} cannot be nil' + end + + @{{{name}}} = {{{name}}} + end + + {{/required}} + {{/isNullable}} + {{/hasValidation}} + {{/isEnum}} + {{/vars}} + # Checks equality by comparing each attribute. + # @param [Object] Object to be compared + def ==(o) + return true if self.equal?(o) + self.class == o.class{{#vars}} && + {{name}} == o.{{name}}{{/vars}}{{#parent}} && super(o){{/parent}} + end + + # @see the `==` method + # @param [Object] Object to be compared + def eql?(o) + self == o + end + + # Calculates hash code according to all attributes. + # @return [Integer] Hash code + def hash + [{{#vars}}{{name}}{{^-last}}, {{/-last}}{{/vars}}].hash + end + +{{> base_object}} + + end diff --git a/config/clients/ruby/template/partial_model_generic_doc.mustache b/config/clients/ruby/template/partial_model_generic_doc.mustache new file mode 100644 index 00000000..95bdb710 --- /dev/null +++ b/config/clients/ruby/template/partial_model_generic_doc.mustache @@ -0,0 +1,28 @@ +# {{moduleName}}::{{classname}} + +## Properties + +| Name | Type | Description | Notes | +| ---- | ---- | ----------- | ----- | +{{#vars}} +| **{{name}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{complexType}}.md){{/isPrimitiveType}} | {{description}} | {{^required}}[optional]{{/required}}{{#isReadOnly}}[readonly]{{/isReadOnly}}{{#defaultValue}}[default to {{.}}]{{/defaultValue}} | +{{/vars}} + +## Example + +```ruby +require '{{{gemName}}}' + +{{^vars}} +instance = {{moduleName}}::{{classname}}.new() +{{/vars}} +{{#vars}} +{{#-first}} +instance = {{moduleName}}::{{classname}}.new( +{{/-first}} + {{name}}: {{example}}{{^-last}},{{/-last}} +{{#-last}} +) +{{/-last}} +{{/vars}} +``` diff --git a/config/clients/ruby/template/partial_oneof_module.mustache b/config/clients/ruby/template/partial_oneof_module.mustache new file mode 100644 index 00000000..04fa0d31 --- /dev/null +++ b/config/clients/ruby/template/partial_oneof_module.mustache @@ -0,0 +1,136 @@ + {{#description}} + # {{{.}}} + {{/description}} + module {{classname}} + class << self + {{#oneOf}} + {{#-first}} + # List of class defined in oneOf (OpenAPI v3) + def openapi_one_of + [ + {{/-first}} + :'{{{.}}}'{{^-last}},{{/-last}} + {{#-last}} + ] + end + + {{/-last}} + {{/oneOf}} + {{#discriminator}} + {{#propertyName}} + # Discriminator's property name (OpenAPI v3) + def openapi_discriminator_name + :'{{{.}}}' + end + + {{/propertyName}} + {{#mappedModels}} + {{#-first}} + # Discriminator's mapping (OpenAPI v3) + def openapi_discriminator_mapping + { + {{/-first}} + :'{{{mappingName}}}' => :'{{{modelName}}}'{{^-last}},{{/-last}} + {{#-last}} + } + end + + {{/-last}} + {{/mappedModels}} + {{/discriminator}} + # Builds the object + # @param [Mixed] Data to be matched against the list of oneOf items + # @return [Object] Returns the model or the data itself + def build(data) + {{#discriminator}} + discriminator_value = data[openapi_discriminator_name] + return nil if discriminator_value.nil? + {{#mappedModels}} + {{#-first}} + + klass = openapi_discriminator_mapping[discriminator_value.to_s.to_sym] + return nil unless klass + + {{moduleName}}.const_get(klass).build_from_hash(data) + {{/-first}} + {{/mappedModels}} + {{^mappedModels}} + {{moduleName}}.const_get(discriminator_value).build_from_hash(data) + {{/mappedModels}} + {{/discriminator}} + {{^discriminator}} + # Go through the list of oneOf items and attempt to identify the appropriate one. + # Note: + # - We do not attempt to check whether exactly one item matches. + # - No advanced validation of types in some cases (e.g. "x: { type: string }" will happily match { x: 123 }) + # due to the way the deserialization is made in the base_object template (it just casts without verifying). + # - TODO: scalar values are de facto behaving as if they were nullable. + # - TODO: logging when debugging is set. + openapi_one_of.each do |klass| + begin + next if klass == :AnyType # "nullable: true" + return find_and_cast_into_type(klass, data) + rescue # rescue all errors so we keep iterating even if the current item lookup raises + end + end + + openapi_one_of.include?(:AnyType) ? data : nil + {{/discriminator}} + end + {{^discriminator}} + + private + + SchemaMismatchError = Class.new(StandardError) + + # Note: 'File' is missing here because in the regular case we get the data _after_ a call to JSON.parse. + def find_and_cast_into_type(klass, data) + return if data.nil? + + case klass.to_s + when 'Boolean' + return data if data.instance_of?(TrueClass) || data.instance_of?(FalseClass) + when 'Float' + return data if data.instance_of?(Float) + when 'Integer' + return data if data.instance_of?(Integer) + when 'Time' + return Time.parse(data) + when 'Date' + return Date.iso8601(data) + when 'String' + return data if data.instance_of?(String) + when 'Object' # "type: object" + return data if data.instance_of?(Hash) + when /\AArray<(?.+)>\z/ # "type: array" + if data.instance_of?(Array) + sub_type = Regexp.last_match[:sub_type] + return data.map { |item| find_and_cast_into_type(sub_type, item) } + end + when /\AHash.+)>\z/ # "type: object" with "additionalProperties: { ... }" + if data.instance_of?(Hash) && data.keys.all? { |k| k.instance_of?(Symbol) || k.instance_of?(String) } + sub_type = Regexp.last_match[:sub_type] + return data.each_with_object({}) { |(k, v), hsh| hsh[k] = find_and_cast_into_type(sub_type, v) } + end + else # model + const = {{moduleName}}.const_get(klass) + if const + if const.respond_to?(:openapi_one_of) # nested oneOf model + model = const.build(data) + return model if model + else + # raise if data contains keys that are not known to the model + raise if const.respond_to?(:acceptable_attributes) && !(data.keys - const.acceptable_attributes).empty? + model = const.build_from_hash(data) + return model if model + end + end + end + + raise # if no match by now, raise + rescue + raise SchemaMismatchError, "#{data} doesn't match the #{klass} type" + end + {{/discriminator}} + end + end diff --git a/config/clients/ruby/template/partial_oneof_module_doc.mustache b/config/clients/ruby/template/partial_oneof_module_doc.mustache new file mode 100644 index 00000000..f86cefe9 --- /dev/null +++ b/config/clients/ruby/template/partial_oneof_module_doc.mustache @@ -0,0 +1,93 @@ +# {{moduleName}}::{{classname}} + +## Class instance methods + +### `openapi_one_of` + +Returns the list of classes defined in oneOf. + +#### Example + +```ruby +require '{{{gemName}}}' + +{{moduleName}}::{{classname}}.openapi_one_of +# => +{{#oneOf}} +{{#-first}} +# [ +{{/-first}} +# :'{{{.}}}'{{^-last}},{{/-last}} +{{#-last}} +# ] +{{/-last}} +{{/oneOf}} +``` +{{#discriminator}} +{{#propertyName}} + +### `openapi_discriminator_name` + +Returns the discriminator's property name. + +#### Example + +```ruby +require '{{{gemName}}}' + +{{moduleName}}::{{classname}}.openapi_discriminator_name +# => :'{{{.}}}' +``` +{{/propertyName}} +{{#mappedModels}} +{{#-first}} + +### `openapi_discriminator_name` + +Returns the discriminator's mapping. + +#### Example + +```ruby +require '{{{gemName}}}' + +{{moduleName}}::{{classname}}.openapi_discriminator_mapping +# => +# { +{{/-first}} +# :'{{{mappingName}}}' => :'{{{modelName}}}'{{^-last}},{{/-last}} +{{#-last}} +# } +{{/-last}} +{{/mappedModels}} +``` +{{/discriminator}} + +### build + +Find the appropriate object from the `openapi_one_of` list and casts the data into it. + +#### Example + +```ruby +require '{{{gemName}}}' + +{{moduleName}}::{{classname}}.build(data) +# => {{#oneOf}}{{#-first}}#<{{{.}}}:0x00007fdd4aab02a0>{{/-first}}{{/oneOf}} + +{{moduleName}}::{{classname}}.build(data_that_doesnt_match) +# => nil +``` + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| **data** | **Mixed** | data to be matched against the list of oneOf items | + +#### Return type + +{{#oneOf}} +- `{{{.}}}` +{{/oneOf}} +- `nil` (if no type matches) diff --git a/config/clients/ruby/template/version.mustache b/config/clients/ruby/template/version.mustache new file mode 100644 index 00000000..2da45be2 --- /dev/null +++ b/config/clients/ruby/template/version.mustache @@ -0,0 +1,8 @@ +=begin +{{> api_info}} + +=end + +module {{moduleName}} + VERSION = '{{gemVersion}}' +end