Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I need to write some api documentation for a REST API that I've created. Are there tools that will stub out a nice html output similar in style to the underscore api documentation? Or perhaps something that will output something as a twitter bootstrap styled html?
I see that docco does annoated code, but I'm actually just looking to document the API only. Ideally I'd like to point a tool at the controller file and have it generate documentation about the methods and routes but not show any source code unless I specifically call out examples.
apiDoc creates a documentation from API annotations in your source code.
Integrated is an API history, with that various API version levels can be compared.
So it can be retraced what changed in the API since the last version.
Demo: http://apidocjs.com/example
Github: https://github.com/apidoc/apidoc
Check out I/O Docs on Github - http://github.com/mashery/iodocs . It's hacked in Node.js, and has a lot of community contribution/involvement. To see it working in the wild:
http://iodocs.docusign.com
http://console.datasift.com/datasift
Uber simple configuration schema (JSON), and hell, if you don't want to describe it all by hand in JSON, use I/O Doctor, a web-based tool for importing/building JSON configs with a UI:
http://iodoctor.net/
Also available on Github at https://github.com/brandonmwest/iodoctor
Let me know if I can help you get started. There are plenty of example configs in the I/O Docs repo. Take care.
I/O Docs or Swagger, which are the most popular RESTful API documentation systems. There is also RAML and Apiary.
test2doc.js helps you generate API documentation from your tests/specs. So you can always get the latest update-to-date API documents, populated with real request/response data.
Test code example:
const doc = require('test2doc')
const request = require('supertest') // We use supertest as the HTTP request library
require('should') // and use should as the assertion library
// For Koa, you should exports app.listen() or app.callback() in your app entry
const app = require('./my-express-app.js')
after(function () {
doc.emit('api-documentation.apib')
})
doc.group('Products').is(doc => {
describe('#Products', function () {
doc.action('Get all products').is(doc => {
it('should get all products', function () {
// Write specs towards your API endpoint as you would normally do
// Just decorate with some utility methods
return request(app)
.get(doc.get('/products'))
.query(doc.query({
minPrice: doc.val(10, 'Only products of which price >= this value should be returned')
}))
.expect(200)
.then(res => {
body = doc.resBody(res.body)
body.desc('List of all products')
.should.not.be.empty()
body[0].should.have.properties('id', 'name', 'price')
body[0].price.desc('Price of this product').should.be.a.Number
})
})
})
})
})
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 6 years ago.
Improve this question
I am developing a mobile app, with the backend in Node.js. Users will interact with the platform almost exclusively through the mobile app. As part of the backend, I am exposing multiple APIs to be utilized by the mobile app -- for example: an API to create an account, send a message, post a picture, etc.
What is best practice to validate the API input?
My thought is to create a module for each API, whose purpose is to extract, sanitize, and validate the relevant attributes from the http-request. For example, the "create an account" API will have an associated AccountCreationRequest module with a validate method in which all account-creation-specific validations will be defined. Each specific validation can then be performed by libraries such as express validator and validator.
exports.AccountCreationRequest = {
init: function(request) {
... extract attributes ...
},
sanitizeAndValidate: function() {
... use express-validator/validator on
attributes such as username, email, etc ...
},
isValid: function() {
... return result of validation ...
}
};
Then, when the backend API receives a request,
var accountCreationRequest = AccountCreationRequest.init(httpRequest);
accountCreationRequest.sanitizeAndValidate();
if (accountCreationRequest.isValid()) {
... store in database and notify client of success ...
} else {
... notify client of failure ...
}
My concern is that N APIs will require N request-validation-modules. However, since each API is unique, I don't think there is much opportunity for code reuse.
If you use express, you can do something like
app.use('/private', function(req, res, next) {
if (/*some condition to check for authentication*/) {
next();
} else { //unauthorized
res.status(401).send('not authorized, please authenticate');
}
});
that will filter everything under the /private path through your authentication condition. You can also use wildcards in the path if you prefer.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 8 years ago.
Improve this question
During the last months, we at work have been looking for a solution to the following problem: front-end developers can't easily modify the appearance of the website without the help of back-end devs.
Our culture as a team is mostly based on full-stack frameworks such as Symfony 2 and Ruby on Rails. We use templating engines but the templates are mostly written by backend-devs according to designers' markups.
The step we are considering to make is separating that monolithic architecture into a backend rest API and a NodeJS server as "UI server". The NodeJS server would handle the client request, consume the backend API and return a rendered template. By specifying clearly the API and the JSONs served, frontend and backend devs could then work in parallel with less problems. More info here: http://www.nczonline.net/blog/2013/10/07/node-js-and-the-new-web-front-end/
The thing is, we strongly believe that this separation is a good thing from an architecture POV, but we fear about the drawbacks. We suspect that it will make things way harder. None of us in the team has never worked with this kind of architectures, so any hint or experience about that would be very valuable.
Is it worth it? When? Why?
What you need to do, is to have a clear line that separates your front-end from back-end. Then whatever the front-end needs from the backend-end team, it will documented comprehensively.
Let's say what you currently have is something like this:
app.get('/', function (req, res) {
database.query('select * from user', function (err, result) {
res.render(result);
});
});
But then then you want to make it like this:
in UI server:
app.get('/', function (req, res) {
request('apiServer/user', function (err, result) {
res.render(result);
});
});
in API server:
app.get('/user', function (req, res) {
database.query('select * from user', function (err, result) {
res.send(result);
});
});
This is good. This will separate the front-end and back-end, but not only logically but also physically by being in different servers.
I believe if they are under the same server it will be just ok. Instead of above, just have them in different files:
in user.js:
exports.getAll = function (cb) {
database.query('select * from user', cb);
};
in server.js:
var user = require('./user');
app.get('/', function (req, res) {
user.getAll(function (err, result) {
res.render(result);
});
});
Why this is better than your solution? Because it separates touching database, and rendering the data, and also it doesn't have a extra http round trip.
Following a MVC pattern, you put files that are like user.js in a models directory, you put files like server.js in a controller directory. You make sure both are documented for front-end developers.
Now if your front-end developers are just gonna make UI changes, they will just touch the HTML files. If they want to add a section with data, they will read the backend documentation, they will add another call to the model to get the data they in the respective controller that renders the HTML.
Just make sure you will standardize everything, so when something new comes along, programmers in your team can somehow predict how the interface is going to be, use a good ORM to the heavy lifting on making database calls. If using an ORM is not your choice then make good abstractions.
So your application in layers can be like this:
Database --> ORM --> Models --> Controllers --> Views(HTML files)
Now the front-end developers, work on the right side the above diagram. They only need to know the documented API of their left side if it's nicely abstracted away, but they don't need to know how it works. Anyone who works on the controllers, only need to know the documented API of their left side which is Models. You can continue it all the way to the database on the left.
Then on each layer you can have unit tests and integration tests all the way to the front to make sure the interfaces are consistent.
And if you're team is large, with a large code base, make sure you always keep the backward compatibility in your interfaces, but with warnings in logs for deprecated stuff. Never try to break anything.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 8 years ago.
Improve this question
I would like to know the structure of a typical NodeJS app, because the more I read and see the projects, the more confused I am, specifically for questions like these (or even more after I updated this question):
Take the MEAN stack for example, from what I know, NodeJS and Express take care of the server part, providing the server interface, etc. MongoDB and Angular are pretty straightforward.
But where should the business logic go? Say if I have a controller.js which contains a function, and the route.js file binds the request with this controller function. My question is: under which module these files belong to/run under (Express or NodeJS?)
Where is the starting point of a NodeJS app? Say index.php is the starting point of a PHP app, but where is it for NodeJS app? I can see that all Nodejs projects have a file called server.js or app.js, etc.(containing something like module.exports = app;) But how can NodeJS know which file to find and execute?
I am a fresh noob on NodeJS, Express, sequelize.js/Mongoose, Jade/EJS but want to get started on a NodeJS project. Could you please elaborate on the actual function that each modules provide and a general introduction of the typical structure for a full JS stacked NodeJS app? Thanks in advance!
Alright, this is a pretty broad question and I'm definitely no expert, but I'll do my best here.
TL;DR
routes are controllers that tell what logic to execute when a user navigates their browser to a certain path within your app, including which views to render and what data to send to those views
models are just that - data models within your application
module.exports = tells a file what exactly it "exports", that is what code needs to be executed or accessible from your main app file.
require(..) includes a module. You can set this on a variable so that you may call module functions later, or simply execute a function if that is all that module.exports returns.
Combining these techniques can help you nail down a solid framework for any of your applications.
Long Answer
Express provides a solid framework for structuring your Node.js application. Node is completely independent of Express, but because of how popular Express is they practically go hand-in-hand. Once installed, Express can be used to generate a scaffold web project (with options) for you to build on top of if you'd like.
Controllers
A generated project will create /routes/index.js, which (if you understand MVC) is essentially your main controller. A route in express is written as so:
app.get('/path', function(req, res, next){ .. } );
Lets break that down: our application variable (app) is being told that on a GET request to '/path' to execute an anonymous callback function with req, res, next variables (request, response, callback respectively). I find it helpful to think of this like a custom event handler.
Its important to note at this point that we could also call app.post with the same syntax for posts to a URL as opposed to gets.
Within our anonymous callback, we handle any incoming data and render a view for the user. This is where most of my business logic ends up, so it actually makes sense to NOT use anonymous functions here. Here's an example of a basic callback that just displays a homepage:
app.get('/', function(req, res, next){
//some business logic
res.render('views/home');
});
When the user tries to GET the index path of our application (/), we simply render our home view that, from the root of our project, is stored in a views folder.
But what if we want to modularize this so that we aren't declaring all of our routes in our main app.js or server.js?
We use module.exports = .. in our modules to tell our server what exactly to include. In my controller, I export a single function that takes the application as an argument and uses that to define our routes like so:
Controllers/User.js
module.exports = function(app){
app.get('/users', function(req, res){
var users = req.db.collection('users').find();
if (!users) {
console.log("no users found");
res.redirect('/');
} else {
res.render('users/index', {users : users});
}
});
};
Don't worry about the req.db code, I attach the database to the request in my application but that isn't done by default. Simply understand that I'm getting a list of 'users' here, and redirecting the user to the index of my app if there aren't any.
Models
Mongoose provides us with a great interface for writing models. With mongoose, writing models is a three step process:
Define a schema
Define model logic
Generate and export the model
Here is an example of a User model:
Models/User.js
var mongoose = require('mongoose'),
userSchema = new mongoose.Schema({
name: { type: String, required: true },
joinDate: {type: Date, default: date.now }
}),
User = mongoose.model('user', userSchema);
module.exports = user;
Server App
module.exports is used to help us define some modularity to our codebase. When we run a node application, we're ultimately running a single JavaScript file (you've already seen that file with server.js or app.js).
To keep this file from getting too big with multiple models and routes, we use require(module) to include code from other JS files. module in our case would be a path to the module we want to require. If you have the following doc structure:
| Controllers
- User.js
| Models
- User.js
| Views
app.js
To include your user controller from app.js, you would write: require('./Controllers/User'). Since our controller modules simply export functions, we can call that function immediately after our require statement by simply adding parentheses at the end (with whatever parameters are required). Including my controllers looks like so:
require('./Controllers/User')(app)
I'm passing in the actual app, because my module (below) simply exports a function that adds business logic to my app's routes. This only needs to be called and never used, so I don't capture my controller as a variable to call methods on later.
Including models is a little different, since we may want to perform some operation that our model defines. We can do this by changing up our require code just a bit:
var User = require('./Models/User');
Now we can call methods of our User model whenever. Mongoose gives us a lot of base functionality for free:
User.find({}, function(err, users){ .. });
The above function will go find all of our users, and then execute an anonymous function with a potential err (is null if no issues) and then a list of our users in JSON format. Pretty nifty.
Combining all of these concepts is how you create a basic web application using Express and Node.js. Please let me know in the comments if there's anything I can clarify about how I use Express. This is very surface level knowledge, and I suggest digging into documentation and looking at plugins to extend the capabilities of your apps. Good luck!
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 7 years ago.
Improve this question
I have a web app that exposes REST webservices.
I want to call those web services using javascript\jQuery (ajax)
Basically I want to render the contents returned by the REST service & perform CRUD openations (which will call other REST services of the external web app)
Anyone has some pointers, articles, sample code that shows how to do it?
Thanks
If I understand your question correctly, there's nothing Liferay-specific in calling external webservices, so you can use any tutorial you find on the web. As you're mentioning you want to use jquery, I assume that those calls will be made from the browser - the only thing that you need to do in Liferay is to make sure that jquery is loaded - for this you can use your theme: Edit portal-normal.vm and include the line to load jquery. Alternatively, as Liferay comes with AlloyUI/YUI, you can load jQuery as a module for AUI with its module yQuery
Here is a sample code using javascript\jQuery to call REST webservices inside portlet (Call Portal Service with Basic Authorization Header):
<%# include file="init.jsp"%>
$(document).on('ready',function(){
var username ="test#liferay.com";
var password ="test";
function make_base_auth(user, password) {
var tok = user + ':' + password;
var hash = btoa(tok);
return "Basic " + hash;
}
$.ajax({
url: 'http://localhost:8080/LiferayJSONWebservices-portlet/api/jsonws/employee/get-employee/employee-id/1',
dataType: "json",
type: "get",
success: function(data){
alert(data.employeeName);
},
beforeSend: function(xhr){ xhr.setRequestHeader('Authorization',make_base_auth(username, password));
},
complete: function(){
},
error: function(){
}
});
});
</script>
have known node.js and express several days ago. I feel they are really cool, however, lacking of something.
I looked the official site, but it just point to Connect's API.
But I can't find a document which teach me how to use a simple function such as expressHTTPServer.get().
Of course I read the nodejs's API, but the Express and Connect seems to extend them very much.
For example, in Express official site:
app = express.createServer();
app.get('/user/:id', function(req, res, next){
loadUser(req.params.id, function(err, user){
if (err)
return next(err);
res.send('Viewing user of csser.com ' + user.name); }
);
});
But sadly, no API document talk me there is expressHTTPServer.get and what it's callback arguments are.
I like to read examples, but I really need an API to learn a new language/library/framework, anyone helps?
Here are the official docs: http://expressjs.com/guide.html
Also, the source can answer a lot of your questions: https://github.com/visionmedia/express
If I understand your question correctly, you want to get to know the API of the req and res parameters passed to your callback, right?
Have a look at http.ServerRequest and http.ServerResponse
Express itself uses Connect which uses the standard Node.js HTTP API. The arguments passed to your callback are monkey patched instances of the described objects.
The Argument "next" is a function you can call if you wish that the request gets handled by another middleware module. If you want to handle the request within your handler, this doesn't need to bother you.