Providing proper documentation in growing number of API platforms and enterprises is a really tedious task. And to keep them updated is another nightmare. This is not an issue with Documentation provider but understanding the documentation itself is a task for developers and partners.
Apigee has this amazing feature called Smart Docs. If you have a specification defined in OpenAPISpec formerly called Swagger specification or a WADL file generating these docs is a child’s play.
Here in this post, we will look at how easy and efficiently the docs are created for your APIs.
Before we go ahead with creating Smart Docs, here’s a feature list of them.
- Method level Details
Every method of your API gets its own page of documentation. This gives you plenty of space to describe the behaviour 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).
- 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 really makes the life of developers and partners easy. They can see the real-time results right from the docs, how amazing.
- a that learn
Smart Docs are called smart because they do not just provide you documentation, but also remembers the field level details, such as values for a query parameter or a header that you had already requested for. I love this feature, where I don’t have to create the whole request again.
- 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! You can template these using the Handlebar syntax and create your own amazing templates to match your branding.
Enough documentation, lets see this thing in action. Follow below steps to generate smart docs for your APIs within minutes.
- Login to developer portal with admin rights. See that black menu strip.
- Go to Content > SmartDocs
- You’ll see a list of smart docs models if you have already in your portal. Else create one by clicking New model link.
- Give name and description of your API model and click creates model.
- Once you have a model created you’ll see an Operations section with a drop down button. Here you can do multiple operations.
- Click the import link from the Operations drop-down. Know that you can do other operations as well.
- Here in import operation, you can import different API descriptor files such as a WADL file/OpenAPI-Spec as JSON or YAML or the exported smart docs template from another Developer Portal.
- Once you imported a file, then Dev portal will create smart docs methods for this model and list all of them. You can select the methods for which you want to create docs pages and render them. From the Update Options block select Render and Publish nodes and click Update.
This will create pages for your selected methods and publish them on Dev Portal.
That’s it. Go to the APIs section on your portal and see the generated docs live and in action.
In coming posts, we will see how we can add restrictions and define different templates for your docs. Stay tuned for more amazing stuff in Apigee domain. A video for this will be coming soon ☺