webida-restful-api

This project contains

• Webida Restful API Spec swagger.yaml
• Javascript Client code generator (see builder/ directory) using Swagger Codegen project:
• Generated Javascript Client sources & docs

Installation

For Webida server & node.js env.

Since server has a dependency to webida-resftul-api package already, server developers may not need to install npm package manually. To use client library in other node.js project, just install npm package from public npmjs registry.

npm install webida-restful-api

For Webida client

This project contains already built api-bunldle.js that can be used as AMD module. So, just import api-bundle.js (and api-bundle.js.map) to client code directly, or add respository to bower.json.

In the case of electron, using node modules in any webida client code is not recommended. Use api-bundle.js directly for better performance & integrity.

For contributors

If you found any bugs/problems in api spec, fill free to report. To extend features, pile an issue and begin discussion. All contributions for builder script & templates are always welcome. Please, read sections below to change spec & generate client codes and do not include 'generated stuffs' in PR.

Build for your own

If you're building webida-based product or service, you may want to customize api spec & regenerate client sources & docs.

Pre-requisites

node.js

Download & install node.js first, if you don't have one yet. For Windows OS, we recommend to use nvm-windows then official installer.

swagger-codegen

Download or build swagger-codegen-cli.jar from Swagger Codegen project. See Swagger Codegen project page for details. Then, copy swagger-codegen.cli to builder/ directory. To change the path of jar file, you should edit build.sh directly.

webpack

Just install webpack to global. (unlike grunt/gulp, local installation is not mandatory yet)

npm install -g webpack

bash

For Windows, use bash from git-for-windows binary to run build.sh

Editing swagger spec & templates

We recommend you to use swagger-editorswagger-editor to edit swagger file & on-the-fly validation. Always be sure that swagger.yaml is validated before building. Or, swagger-codegen-cli will produce some weird errors, hard to find why & where. Do not edit swagger.json file directly, for it's generated from yaml file by build.sh. You may need to add some host, port information in api spec for on-the-fly testing with editor UI, but it's not recommended to publish your spec with 'fixed' api endpoint url, in the view point of devops.

To change package.json generated, edit template files, especially package.mustache. You also need to change build.sh to set codegen configurations. Since current template has some fixes on several issues, starting from the code generated by official templates will be helpful to make your own templates.

Building sources & docs

build.sh will clear pre-generated sources & docs with prior swagger.yaml and regenerate them.

cd builder
./build.sh

Distributing generated stuffs

git_push.sh, generated by swagger-codegen, will help you to upload files to git repository. To publish in public package repositories, read & follow instructions of the package system/manager. You may need to upload all generated stuffs to github or some other central code repository.