I'd like to share my thoughts about https://github.com/swagger-api/swagger-node-express
It has 564 stars on Github, so I think it is justify to use it, but:
Why should I use methods like addGet/addPost and split my controller by HTTP methods
Why should I involve models to routing?
I can use validators for authentication, but I have to choose some paths, that should be protected there. It duplicates logic, that stores in swagger json file.
Isn't the right way to have a static swagger.json and build Express routes on it?
Or maybe I don't understand some practics
Swagger is just a spec. You could hand craft a swagger spec without any code, serve the spec to a swagger-ui compliant page, and it "will work." You could have a fully defined API and "run" it using the UI pages. Same is true for Express without swagger - you can do a lot of neat things! But some effort would be needed to document the API in swagger.
If you want to use swagger-node-express, you are coupling the code to the API documentation. This can save you a lot of time, and keep changes in the same file, etc. However, like all your questions allude to, you must do things the swagger-node-express way. Faster than doing both separately, but there are constraints one must follow.
There are other swagger packages that tackle this from different angles. I've seen some that try to build the swagger docs from the Express/Restify routes automagically. An alternative to swagger-node-express is swagger-tools, which even includes validation, but I'd guess you'd be limited in some fashion to writing Express without any swagger integrated.
You are free to build swagger docs manually (or with some YAML, jsDoc package or a generator), but that would take some extra time after your routes are written. Plus, it's a separate place to maintain your docs and invariably they will be out of sync at some point, if not abandoned. Using swagger-node-express is primarily a time saver and, even with its drawbacks, that might be worth the extra development effort of the alternatives.
Related
I am learning jHipster. My entity relationship model has projects and files. A project can have zero to many files, and a file always belongs to exactly one project.
project <(1:1)-----(0:*)> file
Users interact with the application similar to using an IDE. First, after opening the initial website they always have to select which project they want to work in. (Of course they can also create new projects, or perhaps delete an old one.) Only then they get access to all resources added to a particular project such as files.
As a consequence, my REST API should logically look like this (to get a single file):
GET /projects/{:projectId}/files/{:fileId}
In the backend, depending on whether fileId is a UUID or not, I might even have a method:
findFileByIdAndProjectId(String fileId, String projectId)
The problem is that jHipster creates all entities in a "flat way". Each entity seems to have its own REST API without nesting, and there is simply a reference to an other entity rather than proper composition. Adapting the generated code is quite a bit of work as it requires lots of changes both on the frontend and the backend, but more importantly, it probably breaks the ability to re-create my code when an entity has changed.
I am curious: What different options do I have, and which one would you guys recommend?
Custom code is the way to go though there are few tricks that can help you:
Using DTOs so you can aggregate entities in service layer
Extending generated classes both in backend and frontend so that you don't change generated code, see excellent talk, slides and code samples from Antonio Goncalves
What is the appropriate place to provide RestAPI details while using cucumber? i.e. In Feature file or Step Definition file?
The RestAPI is not really part of the business problem you are solving. Rest is not your core functionality. It is just one, technical, way of using the real functionality you are building.
I would therefore not describe a RestAPI in the feature files using Gherkin. I would hide these implementation details in the glue code connecting the examples written in Gherkin with the system under test.
Cucumber is a tool all about communication between groups of people throughout the business you are working with.
If you're working on a project alone, there is less of the need to describe features in business language (although, it is useful for drafting up ideas using a BDD mindset).
My advice, keep the feature files without code, CSS or any other things that could throw off a layperson. Move these to the step definition file instead, and describe what you're doing in terms that a layperson can understand.
You should store it in the step_definitions file. Keep all the coding tagged to the gherkin steps in the feature file to the step_definitons folder inside which you create a file.
Its always better to keep feature files without the code, they are mainly for better understanding of the testing process and business scenarios and best practise when you view it from BDD perspective.
In case your API values are frequently changing, you can also, mention the values in the cucumber gherkin steps, and pass it as an argument to the step_definitions file. So that any change in the values can be handled in the feature file itself, within the "double quotes" instead of going to the code every-time
On a side note, what gem are you using to test on the REST API? Airborne?
I am new to hapi and for the last few days I've been trying out different project structures in order to keep the concerns separated and the codebase somewhat maintainable while not deviating too much from the "hapi" way of doing things. You can take a look at the folder structure here.
My project consists of a simple RESTful API, so I don't need to worry about views, rendering and so on. What I've ended up doing, and I'm not sure (yet) if this is idiotic or not, is to have the whole API logic (route handling, authorization, db access, etc) registered as a plugin. What this allows me to do is:
easily prefix all the routes with "/api/vX/" for a particular API version
easily swap API versions by registering all the dependencies (basically other plugins) for a particular API version in the plugin itself; this is what I meant in the title by "nested plugins"
I was hoping I could get some insight from other people using hapi and maybe see what what they are using, what's working for them and what's not.
Also, is nesting plugins "hapi"? I've taken a peak at the repos for a few of the popular hapi plugins that are out there and I haven't seen people doing it. Thanks!
I am having a little problem in my workplace where we have a IIS 6 server where Orchard (1.7) will not run. We are planning an upgrade but that's going to take some time.
Since we are using this site on IIS6 only to run one particular custom module we wrote for Orchard (basically a MVC module with its own Controllers/Actions etc.) I was thinking that a temporary solution could be to rip that module out of Orchard and run it independently.
Of course this extraction needs to take into account how many ties I have with the framework. I was wondering if there is some kind of guide to perform this and if there is something I need to take specially into account.
I am using the Users in Orchard so I would probably have to rewrite some users code. I am also using the Authorizer, which again may mean I need to re-wire something else.
It seems like a daunting job so I am looking for some quick tips on how to proceed if you know any.
Thanks a lot!
It all depends on what components you actually use within your module.
Hard to write any tutorial on this, really.
Regarding Orchard.Users - you could drop all related code usages and rely on the default ASP.NET roles-based authentication/authorization model.
If dependency injection is what you want to keep, then you need to integrate it yourself (for Autofac, but other DI containers will also work). Feel free to copy and change any Orchard components that you use, stripping the unneeded code.
In my opinion the hardest thing to strip out and replace would be any code that relies on content items - hope you don't have it. Rewriting this pieces sounds like an overkill. But if you just use IRepository, going for plain NHibernate or EF instead should be quite easy.
I've been using SailsJS for a while now and find it a perfect REST API solution. I'm currently building an app for both Web & Mobile (native) so I need the REST part of SailsJS. I want to build a frontend for my API right now, and I found EmberJS which looks like a promising framework. I've a question about combining those two, they both have their own Routing system, and SailsJS seems to overrule Ember's one.
My guesses would be:
The most easy approach looks like building Sails in a subdirectory
eg. /api/ but I think that's not the nicest way to get this fixed.
I could choose one framework for routing and let the other delegating it's routes. For example passing parameters from SailsJS through EmberJS
How can I use those together correctly?
Think of your backand as something you can't control, like a 3rd party API. The reason is that the optimal routing for a user may differ greatly from what's considered to be good API semantics. It's also not easy to share the route declarations, but it's not a good practice anyway.
My advice:
Use ember-cli to build the frontend. It's a great tool, you'll enjoy it a lot.
Build your Sails-based API in a different repository, using the /api namespace for your API endpoints.
Try to follow the JSON API standard as closely as possible. That'll make easier to connect your backend & frontend, as most data libraries (Ember Data for eg.) tries to adhere those standards as well.
Watch Luke Melia's excellent guide on lighning fast deployment. It'll be the same concept for you but in Sails intead of Ruby/Rails.
All in all, I think if you'll have a great dev experience if you do roughly what I've outlined above. Happy coding!