ramanpalikala / box-openapi

The Box Open API specification for interacting with the Box Content API.

Box Open API specification

The Box Open API specification for interacting with the Box Content API.

Quickstart

The specifications can be obtained by cloning GitHub repository.

git clone https://github.com/box/box-openapi.git

Swagger Codegen

The Swagger Codegen project helps generation of API clients libraries given the Open API specification file. It also generates the documentation automatically.

Java

The Codegen tool generates the default package structure as io.swagger.client for all the specifications. For accessing the Box Content API, all the four specifications may be used. In that case, we will have conflicts of the classes. Therefore, we have to give custom packages for generating client code for each specification.

Box Authorization API specification: Example for creating the custom package io.swagger.authorization.client is as follows.

java -jar swagger-codegen-cli.jar generate -i ${box-openapi}/box-v2-api.authorization.openapi-v2.json -l java -o ${java-client-home}/java-auth --api-package io.swagger.authorization.client

Box OAuth2 Token API specification: Example for creating the custom package io.swagger.token.client is as follows.

java -jar swagger-codegen-cli.jar generate -i ${box-openapi}/box-v2-api.token.openapi-v2.json -l java -o ${java-client-home}/java-token --api-package io.swagger.token.client

Box 2.0 API specification: Example for creating the custom package io.swagger.v2api.client is as follows.

java -jar swagger-codegen-cli.jar generate -i ${box-openapi}/box-v2-api.openapi-v2.json -l java -o ${java-client-home}/java-v2api --api-package io.swagger.v2api.client

Box upload API specification: Example for creating the custom package io.swagger.upload.client is as follows.

java -jar swagger-codegen-cli.jar generate -i ${box-openapi}/box-v2-api.upload.openapi-v2.json -l java -o ${java-client-home}/java-upload --api-package io.swagger.upload.client

C#

C# client generation produces the default package structure same as Java. That leads to the same issue of conflict of classes. For C#, the custom packages need to be given differently.

Box Authorization API specification: Example for creating the custom package io.swagger.authorization is as follows.

Lets create a config.json file with the following content.
{
  "packageName": "io.swagger.authorization"
}

Then, the client code can be generated as follows.
java -jar swagger-codegen-cli.jar generate -i ${box-openapi}/box-v2-api.authorization.openapi-v2.json -l csharp -o ${csharp-client-home}/csharp-auth -c ./config.json

Box OAuth2 Token API specification: Example for cerating the custom package io.swagger.token is as follows.

Lets create a config.json file with the following content.
{
  "packageName": "io.swagger.token"
}

Then, the client code can be generated as follows.
java -jar swagger-codegen-cli.jar generate -i ${box-openapi}/box-v2-api.token.openapi-v2.json -l csharp -o ${csharp-client-home}/csharp-token -c ./config.json

Box 2.0 API specification: Example for creating the custom package io.swagger.v2api is as follows.

Lets create a config.json file with the following content.
{
  "packageName": "io.swagger.upload"
}

Then, the client code can be generated as follows.
java -jar swagger-codegen-cli.jar generate -i ${box-openapi}/box-v2-api.upload.openapi-v2.json -l csharp -o ${csharp-client-home}/csharp-upload -c ./config.json

Troubleshooting

Some of the known issues with using Codegen project with the Box specification files.

Java

RFC-3339 valid date values requires the following change in the Java client code generated by the Codegen project.

Go to ${JAVA-CLIENT-HOME}/src/main/java/com/swagger/client/JSON.java file. The following inner class can be found.

class LocalDateTypeAdapter extends TypeAdapter<LocalDate> {

    private final DateTimeFormatter formatter = ISODateTimeFormat.date();
    
    ...

}

Change the formatter attribute initializtion as follows.

class LocalDateTypeAdapter extends TypeAdapter {

private final DateTimeFormatter formatter = ISODateTimeFormat.dateOptionalTimeParser();

...

}

Javascript

Document generated for the Javascript client has a bug. It generates the statement for retrieving the default client.

var defaultClient = Box20Api.ApiClient.default;

It needs to be changed as below.

var defaultClient = Box20Api.ApiClient.instance;

For uploading a file to work, the callApi method in ApiClient.js needs to be changed. The line that needs to be modified looks like

if (this.isFileParam(_formParams[key])) {
    // file field
    request.attach(key, _formParams[key]);
} else {
    request.field(key, _formParams[key]);
}

It needs to be changed as below.

if (this.isFileParam(_formParams[key]) || key === 'file') {
    // file field
    request.attach(key, _formParams[key]);
} else {
    request.field(key, _formParams[key]);
}

Copyright and License

Copyright 2017 Box, Inc. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.