webida-restful-api v0.8.1
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.