11436 SSO

Apigee SmartDocs: Introducing Smarter API Documentation

May 02, 2014

Enterprises and their API teams struggle to provide up-to-date, meaningful, and engaging documentation for their APIs. As as result, app developers and partners can find it challenging to understand the technology, the use case, and the benefits behind API products. This, in turn, hampers adoption and leads to content that’s hard to maintain.  

We’ve responded to our customers’ struggle to leverage the basic functionality offered by Swagger, WADL, or manually created documentation by introducing Apigee SmartDocs.

SmartDocs is method-level API documentation that’s detail-rich and offers both internal and external SEO benefits. API providers can: generate docs by leveraging handlebars-driven templates; test the accuracy of their documentation with live requests; and control the layout, interactions, and look of your docs.

Your app developers and partners can make API requests without leaving the page, work faster as SmartDocs learns the parameter values they like to use, and benefit from accurate, model-driven documentation.

SmartDocs is now available in beta to all developer portals in the cloud (on-premises will be available soon). Now you can easily create and maintain beautiful, interactive API documentation.

Get a taste of the end-user experience now by browsing the documentation for the Apigee Edge API:


Four key SmartDocs features:

  1. Method-level detail: Every method of your API gets its own page of documentation. This gives you plenty of space to describe the behavior of that method in detail. Not only does that help provide necessary information to developers, the documentation itself is indexed, which brings SEO benefits to internal (portal) search results as well as external search results (Google ranking, for example).

  2. Interactive requests: Developers can send requests without leaving your docs. SmartDocs guides developers to build well-formed requests and to sign them with their credentials. This helps you minimize a crucial adoption metric: time to first request. And because your writers can test their work in-situ, it should improve the accuracy of your documentation.

  3. Docs that learn: SmartDocs remembers the values that each developer uses for subsequent requests. This makes SmartDocs a tool that gets better the more you use it, and it helps developers move faster.

  4. Easy to maintain: You have complete control over the layout, interactions, and look and feel. Plus, in-line editing allows you to change what you can see, right from the generated docs!

Ready to begin? The best place to start is the introduction to SmartDocs. Today SmartDocs supports OAuth 2.0's webserver flow, custom token authentication (API keys), and HTTP basic authentication. If you have a developer portal and an existing description of your services in Swagger or WADL (as used by Apigee API consoles) format, you can have SmartDocs published in as little as 10-15 minutes.

Scaling Microservices