11436 SSO

Apigee Edge Cloud Release: SmartDocs Graduates to General Availability

Jun 01, 2015

High school seniors aren't the only ones graduating this week—we're thrilled to announce that today SmartDocs is graduating from beta and into general availability.

Some of the highlights include:

  1. Support for Swagger 2.0—a year ago we worked with Reverb to kick off the Swagger 2.0 working group, and in March, core Swagger Java projects began leveraging the new spec. Now when you import Swagger, SmartDocs will include security and schemas.

  2. Unlike Swagger 1.2, Swagger 2.0 supports single-file descriptions including via YAML or JSON file upload, so there are no longer requirements to host your Swagger descriptions with 2.0.

  3. Overhauled workflows and improved usability when using SmartDocs within the developer portal. Now it's much easier to get started and manage how you publish your documentation—just look for the SmartDocs entry in the Content admin menu.

  4. Better separation of authentication schemes into a "security" object at the revision level and client authentication configuration at the template level.

  5. Improvements to the visual design of the templates that generate SmartDocs.

Screen Shot 2015-06-01 at 7.29.21 pm.png

Note: if you have been using SmartDocs during the beta, be sure to read the documentation on the upgrade process.

One question that was asked during the beta was, "Doesn't SmartDocs compete with Swagger?" (usually in comparison to Swagger-UI). The answer: the two complement each other. Most API projects start off lean, and the primary audience for API documentation is internal, so Swagger-UI is often sufficient. But as your API program grows, a one-method-per-page documentation approach starts to become more important, since it offers a higher level of detail and discoverability.

Furthermore, as you grow your developer audience, searchability of your docs becomes critical, which is why SmartDocs content is fully indexed by the developer portal and if your documentation is open, it can be indexed by the Googles of the world. Best of all, by supporting Swagger as an import format, you get to decide when it's most appropriate for you to take your docs to the next level in order to better serve your developers.

Now that SmartDocs is out of beta, you'll start to see other integrations with Edge components begin to come online beyond SmartDocs in the developer portal. In the meantime, if you have questions about moving your models and templates from the beta, the community forums are a good place to start in the developer portal channel, even if it's just to show off how you've succeeded in creating a great developer experience in your portal.

SmartDocs' general availability is part of a new Apigee Edge cloud release (check out the release notes), which includes a handful of new features and enhancements, including a new beta version of the API proxy editor.

Photo: John Walker/Flickr

Scaling Microservices