chore(spec): initial commit

.gitignore

@@ -0,0 +1,36 @@
+# Dir for API portal deploy
+web_deploy
+
+# Logs
+logs
+*.log
+npm-debug.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directory
+node_modules
+
+# Optional npm cache directory
+.npm
+
+# Optional REPL history
+.node_repl_history
+
+# Virtualenv
+spec/.venv

.travis.yml

@@ -0,0 +1,15 @@
+language: node_js
+node_js:
+  - "node"
+deploy:
+  - skip_cleanup: true
+    provider: script
+    script: npm run deploy
+    on:
+      branch: master
+  - skip_cleanup: true
+    provider: script
+    script: npm run deploy-branch
+    on:
+      all_branches: true
+      condition: '"$TRAVIS_BRANCH" != "master" && "$TRAVIS_BRANCH" != "gh-pages"'

README.md

@@ -0,0 +1,28 @@
+# Flat OpenAPI Specification
+[![Build Status](https://travis-ci.org/FlatIO/api-reference.svg?branch=master)](https://travis-ci.org/FlatIO/api-reference)
+
+## Links
+
+- Documentation(ReDoc): https://flatio.github.io/api-reference/
+- Look full spec:
+    + JSON https://flatio.github.io/api-reference/swagger.json
+    + YAML https://flatio.github.io/api-reference/swagger.yaml
+- Preview spec version for branch `[branch]`: https://flatio.github.io/api-reference/preview/[branch]
+
+**Warning:** All above links are updated only after Travis CI finishes deployment
+
+## Working on specification
+### Install
+
+1. Install [Node JS](https://nodejs.org/)
+2. Clone repo and `cd`
+    + Run `npm install`
+
+### Usage
+
+1. Run `npm start`
+2. Checkout console output to see where local server is started. You can use all [links](#links) (except `preview`) by replacing https://flatio.github.io/api-reference/ with url from the message: `Server started <url>`
+3. Make changes using your favorite editor or `swagger-editor` (look for URL in console output)
+4. All changes are immediately propagated to your local server, moreover all documentation pages will be automagically refreshed in a browser after each change
+5. Once you finish with the changes you can run tests using: `npm test`
+6. Share you changes with the rest of the world by pushing to GitHub :smile:

gulpfile.js

@@ -0,0 +1,50 @@
+var gulp = require('gulp');
+var util = require('gulp-util')
+var gulpConnect = require('gulp-connect');
+var connect = require('connect');
+var cors = require('cors');
+var path = require('path');
+var exec = require('child_process').exec;
+var portfinder = require('portfinder');
+var swaggerRepo = require('swagger-repo');
+
+var DIST_DIR = 'web_deploy';
+
+gulp.task('serve', ['build', 'watch', 'edit'], function() {
+  portfinder.getPort({port: 3000}, function (err, port) {
+    gulpConnect.server({
+      root: [DIST_DIR],
+      livereload: true,
+      port: port,
+      middleware: function (gulpConnect, opt) {
+        return [
+          cors()
+        ]
+      }
+    });
+  });
+});
+
+gulp.task('edit', function() {
+  portfinder.getPort({port: 5000}, function (err, port) {
+    var app = connect();
+    app.use(swaggerRepo.swaggerEditorMiddleware());
+    app.listen(port);
+    util.log(util.colors.green('swagger-editor started http://localhost:' + port));
+  });
+});
+
+gulp.task('build', function (cb) {
+  exec('npm run build', function (err, stdout, stderr) {
+    console.log(stderr);
+    cb(err);
+  });
+});
+
+gulp.task('reload', ['build'], function () {
+  gulp.src(DIST_DIR).pipe(gulpConnect.reload())
+});
+
+gulp.task('watch', function () {
+  gulp.watch(['spec/**/*', 'web/**/*'], ['reload']);
+});

package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@flat/api-reference",
+  "version": "0.0.1",
+  "dependencies": {
+    "bower": "^1.7.7",
+    "connect": "^3.4.1",
+    "cors": "^2.7.1",
+    "deploy-to-gh-pages": "^1.1.0",
+    "gulp": "^3.9.1",
+    "gulp-connect": "^4.2.0",
+    "gulp-util": "^3.0.7",
+    "portfinder": "^1.0.3",
+    "shelljs": "^0.7.0",
+    "swagger-repo": "^1.0.0"
+  },
+  "private": true,
+  "scripts": {
+    "deploy": "npm run build && deploy-to-gh-pages --update web_deploy",
+    "build": "node ./scripts/build.js",
+    "swagger": "swagger-repo",
+    "test": "swagger-repo validate",
+    "start": "gulp serve",
+    "deploy-branch": "node ./scripts/deploy-branch.js"
+  }
+}

scripts/build.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+'use strict';
+var Path = require('path');
+
+require('shelljs/global');
+set('-e');
+
+mkdir('-p', 'web_deploy')
+
+cp('-R', 'web/*', 'web_deploy/');
+
+exec('npm run swagger bundle --        -o web_deploy/swagger.json');
+exec('npm run swagger bundle -- --yaml -o web_deploy/swagger.yaml');

scripts/deploy-branch.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+'use strict';
+require('shelljs/global');
+var path = require('path');
+
+set('-e');
+set('-v');
+
+var branch = process.env.TRAVIS_BRANCH && process.env.TRAVIS_BRANCH.toLowerCase();
+if (branch && branch !== 'gh-pages') {
+  var branchPath = path.join('.tmp', 'preview', branch, '/');
+  mkdir('-p', branchPath);
+  exec('npm run swagger bundle -- -o ' + branchPath + 'swagger.json');
+  cp('web/index.html', branchPath);
+  exec('deploy-to-gh-pages --update .tmp');
+}

spec/README.md

@@ -0,0 +1,13 @@
+## Flat API Specification
+
+The public API specification is available in `swagger.yml`.
+
+Some indications if you want to make some changes:
+- Before making large changes, please open an issue in this repository.
+- Before opening a PR, please lint the YAML specification:
+
+```bash
+virtualenv .venv && source .venv/bin/activate
+pip install -r requirements-dev.txt
+./spec-lint.py
+````

spec/code_samples/README.md

@@ -0,0 +1,9 @@
+Code samples
+=====
+
+Generate [x-code-samples](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-code-samples)
+Path  `<lang>/<path>/<HTTP verb>.<extension>` where:
+  * `<lang>` - name of the language from [this](https://github.com/github/linguist/blob/master/lib/linguist/popular.yml) list.
+  * `<path>` - path of target method, where all slashes replaced with `@` sign.
+  * `<HTTP verb>` - verb of target method.
+  * `<extension>` - ignored.

spec/requirements-dev.txt

@@ -0,0 +1 @@
+ruamel.yaml==0.14.5

spec/spec-lint.py

@@ -0,0 +1,31 @@
+#! /usr/bin/env python
+
+import ruamel.yaml
+from ruamel.yaml.scalarstring import PreservedScalarString, preserve_literal
+from ruamel.yaml.compat import string_types
+
+infname = "swagger.yaml"
+
+def walk_tree(base):
+	if isinstance(base, dict):
+		for k in base:
+			v = base[k]
+			if isinstance(v, string_types) and '\n' in v:
+				base[k] = preserve_literal(v)
+			else:
+				walk_tree(v)
+	elif isinstance(base, list):
+		for idx, elem in enumerate(base):
+			if isinstance(elem, string_types) and '\n' in elem:
+				base[idx] = preserve_literal(v)
+			else:
+				walk_tree(elem)
+
+
+with open(infname, 'r') as fi:
+	data = ruamel.yaml.round_trip_load(fi)
+
+walk_tree(data)
+
+with open(infname, 'w') as fo:
+	ruamel.yaml.round_trip_dump(data, fo, width=10000)