xojo-client.README.mustache Maven / Gradle / Ivy
# Xojo API client for {{{projectName}}}
{{#appDescriptionWithNewLines}}
{{{.}}}
{{/appDescriptionWithNewLines}}
## Overview
This API client was generated by the [OpenAPI Generator](https://openapi-generator.tech) project. By using the [openapi-spec](https://github.com/OAI/OpenAPI-Specification) from a remote server, you can easily generate an API client.
- API version: {{appVersion}}
- Package version: {{packageVersion}}
{{^hideGenerationTimestamp}}
- Build date: {{generatedDate}}
{{/hideGenerationTimestamp}}
- Build package: {{generatorClass}}
{{#infoUrl}}
For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
{{/infoUrl}}
## Installation
This project contains generated code suitable for both Desktop and Console applications on all operating systems.
The code is generated for Xojo's API v1.
The generated code is packaged into a single Module (`{{{projectName}}}`), which we suggest copying to your project after opening the generated `{{{projectName}}}.xojo_project` in [Xojo](https://xojo.com/). Working in the generated Xojo project is not recommended.
> See also Xojo's [Sharing code among multiple projects](https://documentation.xojo.com/topics/code_management/sharing_code_among_multiple_projects.html).
This project depends on [Xoson](https://github.com/Topheee/xoson) `v2.2.0` (and above). Download it to your computer:
```shell
git clone 'https://github.com/Topheee/xoson.git'
```
Open the `Xoson.xojo_project` from the cloned git repository with Xojo and copy the `Xoson` module to your project. Similarily, open the `{{{projectName}}}.xojo_project` file with Xojo and copy `{{{projectName}}}` to your project.
> Since Xojo currently has no package manager, you need to manually copy both the `Xoson` and the `{{{projectName}}}` modules to your Xojo project.
Both modules must not be copied into another module, but must reside at the top level of your project.
### Customization
The generator can be configured with the following options.
Option | Used | Description
--- | --- | ---
`projectName` | `{{projectName}}` | The name of the generated project and module.
`nonPublicApi` | `{{nonPublicApi}}` | Generate `Protected` instead of `Public` methods, if set.
`library` | `{{library}}` | Internal Xojo standard library object to use. Currently only `httpsocket` (`HTTPSocket` class) is supported.
`serializationLibrary` | `{xoson` | Internal library to use for serialization. Currently only `xoson` ([Xoson](https://github.com/Topheee/xoson) library) is supported.
`supportsAsync` | `{{supportsAsync}}` | If `true`, generated APIs will use callbacks instead of blocking the main thread.
### Usage
Communication with the OpenAPI server is done by instantiating one of the classes below `{{{projectName}}}.{{{apiPackage}}}`, configuring it - by setting `BasePath`, `UseHTTPS`, and `Port` - and invoking the `{{#nonPublicApi}}Protected {{/nonPublicApi}}{{^nonPublicApi}}Public {{/nonPublicApi}}` methods.
{{#supportsAsync}}
The methods always return immediately and the network communication is done in the background. To obtain the results and errors of each request, you need to implement the respective `CallbackHandler` interfaces:
{{#apiInfo}}{{#apis}}- `{{{projectName}}}.{{{apiPackage}}}.{{{classname}}}CallbackHandler`
{{/apis}}{{/apiInfo}}
Create an object of your implementing class and assign it to the `CallbackHandler` property of the API object.
This callback handler has exactly one method definition for each operation. This method is invoked when the operation finishes. It's first parameter `status As {{> nameException}}` is always set. If `status.IsError` is `False`, the operation succeeded and the return value (either `data` or `file`) - if available - contains valid information.
{{/supportsAsync}}{{^supportsAsync}}
If the methods returns `True`, the API request was successful. Otherwise, the `localOutStatus` parameter contains information about the failure. Note that despite this `ByRef` parameter, the methods may still raise an exception!
The method blocks until the response is received.
{{/supportsAsync}}
> The property `AdditionalHeaders` allows sending further headers with each request. Set it to a new `Dictionary`, with the Keys being the header names and the values either being a single String or an array of Strings.
__Error handling__, as well as status reporting, is done via class `{{> nameException}}`. Note that an instance of this class does not always indicate an error - check `IsError` to find out.
- `ErrorNumber` is set to one of the `{{{projectName}}}.kError` constants, or `0` in case of no error.
- `HTTPStatus` is set to the HTTP status code as returned by the server. If the error is unrelated to HTTP, this property is `-1`.
- `SocketCode` contains the socket error, if any; otherwise `0`.
## Documentation for API Endpoints
All URIs are relative to *{{basePath}}*
Class | Method | HTTP request | Description
------------ | ------------- | ------------- | -------------
{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{{projectName}}}.{{{apiPackage}}}.{{{classname}}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{summary}}
{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
## Documentation For Models
{{#models}}{{#model}} - [{{{projectName}}}.{{{modelPackage}}}.{{{classname}}}]({{modelDocPath}}{{{classname}}}.md)
{{/model}}{{/models}}
## Documentation For Authorization
{{^authMethods}} All endpoints do not require authorization.
{{/authMethods}}{{#authMethods}}{{#last}} Authentication schemes defined for the API:{{/last}}{{/authMethods}}
{{#authMethods}}## {{{name}}}
{{#isApiKey}}- **Type**: API key
- **API key parameter name**: {{{keyParamName}}}
- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
{{/isApiKey}}
{{#isBasicBasic}}- **Type**: HTTP basic authentication
{{/isBasicBasic}}
{{#isBasicBearer}}- **Type**: Bearer authentication{{#bearerFormat}} ({{{.}}}){{/bearerFormat}}
{{/isBasicBearer}}
{{#isHttpSignature}}- **Type**: HTTP signature authentication
{{/isHttpSignature}}
{{#isOAuth}}- **Type**: OAuth
- **Flow**: {{{flow}}}
- **Authorization URL**: {{{authorizationUrl}}}
- **Scopes**: {{^scopes}}N/A{{/scopes}}
{{#scopes}} - **{{{scope}}}**: {{{description}}}
{{/scopes}}
{{/isOAuth}}
{{/authMethods}}
## Author
{{#apiInfo}}{{#apis}}{{#-last}}{{infoEmail}}
{{/-last}}{{/apis}}{{/apiInfo}}