threedi-api-openapi-client v3.0.2-beta1

Introduction

This Javascript library was automatically created by openapi-generator, from threedi-api's Swagger spec.

It is intended to be used from Typescript, and uses the fetch function so it is not for IE11.

Usage

Add threedi-api-openapi-client to your dependencies, with e.g. yarn add.

Now code the following should work:

import * as api from 'threedi-api-openapi-client';

console.log('api', api);
new api.OrganisationsApi().organisationsList({}).then(response=>{
  console.log('organisations', response);
});

Updating the library

In case a new version of the generator is needed:

• Create a new swagger.yml in ONE OF the following ways:

Get the swagger.yml applicable for staging on this url: https://api.staging.3di.live/v3.0/swagger.yaml

OR in the threedi-api repository, with this command:

docker-compose run --rm api python manage.py  generate_swagger -m --user tom.deboer -u http://localhost:8000  --api-version 3.0 -o -f yaml swagger.yaml

(replace tom.deboer with the Django username of an existing admin user, and the api-version with the correct one)

• Place the swagger.yml file in this repository and run

./generate_openapi_typescript_fetch.sh

From inside this repository's root directory.

This installs a Docker image if you don't have it yet and uses it to generate the new version of the library. As the Docker-generated files are owned by root they need to be chown'ed to you, and that requires sudo, so you are asked for a password.

It will install the Typescript dependency using npm and then build the library.

You may see a long list of error messages, but these are not problematic.

Now in the file runtime.ts change the line of the const BASE_PATH to:

export const BASE_PATH = "/v3";

Update the version number in package.json. We keep the version of this package equal to the version of the swagger.yaml file (defined in its "framework release"). However, sometimes multiple releases with the same swagger.yaml are needed (because of mistakes made, for instance). Semver does not allow a fourth part to the version number, and additions like "1.0.61-1" are considered to be prereleases, and are sorted before "1.0.61". There we use the next version number (1.0.62 in this case, for swagger.yaml 1.0.61) with a "-beta1" addition.

! IMPORTANT ! After changing runtime.ts and package.json, run npm run build !

Publish to NPM with npm publish.

Updating the Docker Image Version

The openapi tool used to generate typescript defenitions from the swagger.yml file is run inside a docker. The file generate_openapi_typescript_fetch.sh contains a docker pull command to download the docker image. This docker image now is hardcoded to version v4.1.1 This is because newer docker images (at least untill v4.2.1) create typescript defenitions that do not send the authentication cookie. The reason for this is yet unknown, but for now we solved this by using an older docker image.

Testing the npm package locally

This repo is generally used as a npm library. To test it during development it is however not so practical to keep creating a new release with "npm publish" every time. You can install this package from your local machine (instead of from the npm registry) with one of the following commands:

npm install <local_absolute_path_to_this_repo>

yarn add <local_absolute_path_to_this_repo>