We are making a versioned REST API using Microsoft Web API 2. The versions are at different paths ("api/v1/...", "api/v2/...", etc.) We're using attribute routing, with regex and range constraints for routes.
Using the built-in Web API 2 help page generation (or any third-party help documentation generator), how can we generate a separate help page for each API version? It's acceptable if we need to hook into the help page generation mechanism (how?) to add custom processing, or to add hints to the documentation generator such as hint attributes or additional XML comment tags.
Related
I want to design my web api using swagger, but the problem is I have to write all the yaml code myself, which in itself is a time consuming and tedious process. Can this process be automated?
I tried searching but did not anything useful.
Is auto-generation of yaml code for api design even possible before creating the api itself.
If yaml code can't be generated automatically then why use swagger for api design.
Any help will be appreciated. Thanks!
You can use swashbuckle instead of swagger (or alongside it, but i suggest just picking one)
https://github.com/domaindrivendev/Swashbuckle.AspNetCore#getting-started
They changed the docs since i've used it, however there's this tool you can use that scans your asp.net core project, looks at all controllers and routes and generates an opeapi document for you.
It can also generate client code and a bunch of other things.
I am new guy to Demandware and I am switching from Magento to Demandware.
Demandware is not opensource I am not getting proper tutorials, stuff to understand the concepts of it.
I am from Magento so I know the Magento MVC structure.
But in Demandware we have different concepts like pipelines, pipelets, ISML scripts, ECMA script, DW scripts etc.
I want to know the MVC pattern of Demandware.
How it works and what are the basic concept I need to concentrate?
I would suggest to request a Demandware XChange account as soon as possible for you, so that you get access to the Demandware community portal and also to the API documentation.
In short:
Models are Demandware Forms and Demandware API objects
Controllers are Demandware Pipelines (there are JavaScript Controllers that are recently released, you may find these easier to understand if you have Node.js experience). These can call DW Scripts (DemandwareScript is based on ECMAScript standard 5.0 for JavaScript with some extensions like E4X and optional types)
Views are the isml templates. You should avoid including a lot of logic in them, either with isml tags like isif, isloop, etc. or with isscript.
Any further questions - let me know.
Hope this helps,
Zlatin
I hope you'll be able to avoid pipelines and dwscript. Those are a bit older. The most recent version works with plain old JavaScript, with pipelines being replaced by controllers.
Be aware that the underlying JavaScript engine is Rhino, which isn't really modern.
The Demandware documentation is open source now anyone can access to without having an exchange account it has the latest SFRA(javascript) based concepts as well
here is the link for the docs
Demadware Documentation
Demandware is very much designed around the MVC concept (in theory). The pipelines are basically your controllers and each pipeline filename (the xml file) is the first part of the URL and the start nodes inside the pipeline are the second part of the URL that basically represent the controller (eg Cart.xml has a start node called Show, so the url is Cart-Show). At the end of the pipeline flow chart is, usually, an interaction node to that links to an ISML file, those are basically the View and are HTML with some minor Demandware-specific markup.
Typically in the MVC world you try to prevent putting business logic in the views, however if you use SiteGenesis as your starting point you'll find that not to be the case on most of the pages. If you switch to using Javascript Controllers instead of Pipelines, then it'll be closer to the Magento style of MVC (but using NodeJS-like syntax).
I am using GIGYA gamification custom actions for a POLL in a website. As per the documentation I have created a Custom Action. Then, I created a html page which has the poll layout and included Gigya's api key and used gigya.gm.notifyAction function. My questions are -
This function as per my understanding will notify the custom action. How can I and where will i see the results. Do i need to use another function to get the counts.
Can someone provide a small custom JS code for Gigya.
We do have an example site which will show you how this is implemented. Although the site uses loyalty, you should be able to adapt it to what you want it to show using gamification. The url is: http://raas-demo.gigya.com/
You can also download the websites source code as well.
This will explain about:
http://developers.gigya.com/display/GD/Loyalty
Kind Regards
Nadeem R
How are people managing multiple API versions with API Blueprint?
It doesn't seem that the format supports version sections within a single file, so I'm left thinking that multiple files with indicators in the filename are the best option.
We want to leverage the tools to create a central mock-server and doc commons, and will need to handle evolving multiple versions of each API.
Managing multiple versions via branches seems inconvenient for us, so we render the entire document with multiple versions of APIs in one page. Our users need to be able to read both versions by just prepending v1 or v2 in front of the URL. So, we have a node app that handles the documentation requests and renders the doc via aglio node module.
The following is how we organize the docs.
Users can request /docs/en/spec.
The en part determines the language of the document as we support different languages.
Because the entire document is pretty huge we split it into files based on the Blueprint Group (the thing that starts with # Group GroupName)
When a request comes in, we first look if we have previously compiled the doc and have a cached version, so we don't recompile every time (it's pretty intensive work especially when the doc is large).
If we have no cached version, we read all *.md files in the docs/en directory.
Sort the filenames alphabetically, concat their contents, and pass to aglio which produces a nice html content. We cache this content into a file and later pipe it to the client on each request.
The UI provides the table of contents (side menu on the left) which has, for instance, the following format.
Auth
Projects
Project Users
...
Groups
Groups v2
Now each Group of APIs has a distinct URL which is prepended with /v1 by default. When we introduce a new version of a specific API, we create a new # Group Groups v2 which is prepended with /v2. This way our users can see and choose multiple versions of the APIs in one page.
The nice things about the aglio node module is that it provide multiple themes for the UI which provides a nice navigation so that our users don't feel the page is too overloaded. Among the themes you can choose either single-page UI or multi-page UI where on selection of the API the page with the corresponding API is loaded and the URL is changed.
Implementing this logic is very simple. Hope this helps.
There is another idea which we are considering right now but haven't started just yet. It is to avoid splitting APIs into different # Groups and instead modify the Jade template used by aglio and make sure it supports multiple versions out of the box.
It might be best to version the blueprint file in a versioning repository and treat different branches as different API versions. You can even have the blueprint in the same repo/branch as the API server implementation.
If you're versioning using GitHub, Apiary can connect to GitHub and you can setup different branches to be picked up by different documentations in Apiary.
I'm developing a community extension for Magento, when a product search is detected, some JavaScript included with the extension needs to query the Magento API to get a larger number of results than are rendered on page.
I have the API configured, responding, and returning useful data, but I'm struggling to find a way to apply a query to the API call. I've tried adding ?q= or ?keyword= and similar, but it continues to return the same set of data without any filtering applied. Countless passes through Google, Magento StackExchange, and various Magento developer forums haven't made it clear one way or another if this is even possible.
Does the REST API support keyword / phrase searches, or will my extension need to include a block that adds this functionality to the REST API?
Did you take a look at Magento API Filtering .
You could also create you own Custom API or Extending the Core API