api-first-spec v2.0.6
api-first-spec
Sync your API implementation and documents always!
Motivation
I'm a backend engineer.
I have to write API document for frontend engineers.
It is very bored. And I and most of my co-workers often forget to update document after API improvement.
This is a solution for that situation.
Goal
- Describe API specification as simple as possible.
- Any engineers who doesn't know about api-first-spec can read it.
- Test API specification itself.
- Make API test as easy as possible.
- Force to sync API implementation and document always.
How it works
- Define API spec as a JavaScript object.
- You can make e2e test with that defined API object.
- When you make some update on that API and not update API spec, test will fail.
- Unknown field exists in API response
- Unknown parameter exists in API parameters
- You have to update spec object to pass test. -> Sync API implementation and document always!
Install
npm install api-first-spec
How to define spec
Example is like this.
var spec = require("../lib/api-first-spec");
var API = spec.define({
name: "Sign in",
description: `
Sign in to the system by email and password.
`,
endpoint: "/auth/signin",
method: "POST",
request: {
contentType: spec.ContentType.URLENCODED,
params: {
email: "string",
password: "string",
remember_me: "boolean"
},
rules: {
email: {
required: true,
email: true
},
password: {
required: true,
minlength: 8,
maxlength: 40
}
}
},
response: {
contentType: spec.ContentType.JSON,
data: {
code: "int",
message: "string",
result: {
id: "int",
name: "string",
imageUrl: "string",
lastLogin: "datetime"
}
},
rules: {
code: {
required: true
},
result: {
required: function(data) {
return data.code === 200;
}
},
"result.id": {
required: true
},
"result.name": {
required: true
},
}
}
});
module.exports = API;
Probably most of engineers can read it without special knowlegde. Detailed reference is here(Reference.md#Define Spec)
How to make test
You can make test with mocha
Example is like this.
var assert = require("chai").assert;
var SigninAPI = require("./Signin.spec.js");
describe("signin", function() {
var host = spec.host("localhost:9000");
it("succeed with corrct email and password", function(done) {
return host.api(API).params({
"email": "test@test.com",
"password": "password"
}).success().then(data => {
assert.equal(data.code, 200);
assert.equal(data.result.id, 1);
assert.equal(data.result.name, "test");
});
});
it("with wrong email should be badRequest", () => {
return host.api(SigninAPI).params({
email: "unknown@test.com",
password: "password"
}).badRequest();
});
it("with wrong password should be badRequest", function(done) {
return host.api(API).params({
"email": "test@test.com",
"password": "PASSWORD"
}).badRequest();
});
});
spec#host
method returns a HttpClient.
It can make several API calls with defined API.
It handles cookie properly.
Detailed reference is here(Reference.md#Make Test)
4 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
8 years ago
8 years ago
8 years ago
9 years ago
9 years ago
9 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago