SmartBear Reports
IndexClose

    API Documentation

    Documentation is most beneficial when accessible, consistent, stays up to date, and validated as part of the delivery cycle. Documentation allows for ease of use and alignment with API consumers and self-service users.

    A lack of documentation is like navigating without a map – it leads to uninformed decisions that send you in the wrong direction. In terms of API quality, documentation should be non-negotiable for all teams. This section explores why its use by organizations is so critical to success in the API lifecycle.

    Download the year on year trend report

    Process

    Documentation is a Priority to Most Organizations

    0%5%10%15%20%25%30%35%I am not sureNo and documentation is not a priorityNo but we plan to in the futureYes but documentation is not a priorityYes and documentation is a top priority6%7%20%28%39%

    This year, a substantial proportion of organizations reported that they do have API documentation in place – or, in the small case they do not (20%), they have intentions to do so in the future.

    We see that the value of API documentation is universally recognized across all organizations – especially those with more than 10,001 employees while smaller organizations (500 or less employees) have documentation in place but don’t have it as high a priority as their larger counterparts.

    Obstacles

    Limited Time Due to Workload Remains the Biggest Obstacle to Keeping API Documentation Up to Date

    0%

    We have found that according to 62% of survey participants, the biggest obstacle to providing up-to-date API documentation is “Limited Time”. Upon further analysis, we found that the documentation process of mid-size and large organizations was mostly impacted by “Limited Time Due to Workload”. These same cohorts – 101-500 and 1,001 or more employees – also conveyed the impact of documentation being out of sync as a key obstacle. “Lack of Budget” was the lowest impact but evenly felt across the entire survey group.

    Important Features

    Most Organizations Who Have External APIs Expose Them Through API Gateways

    When it comes to exposing public APIs, we wanted to know which developer API portal, management and gateway tools were used by respondents. The results showed that 80% of survey participants expose third party APIs with the most common way to do so using an “API Gateway” (slightly less than one third) followed by “API Management Tools” (about one fifth).

    Show Me How it's Done....Examples are The Most Important Aspect of API Documentation

    0%

    For this question, we asked participants to select the top five most important aspects of documentation. Respondents expressed their favoritism for “Examples in API Documentation” (66%) followed by “Status and Errors” (59%), “Authentication” (55%), “Parameters” (50%) and “HTTP Requests” (49%) rounding out the top five.

    Segmenting by role, we found the most popular role of survey respondents, QA Engineers/Automation Engineers, placed the top importance, evenly, on four specific aspects of documentation: “Examples”, “HTTP Requests”, “Parameters” and “Status and Errors”.

    Documentation Quality

    One Third of Survey Participants Feel Their Documentation Needs Improvement

    0%

    Most organizations (51%) feel positive about their documentation having rated it from “Good” to “Average”; a select few (9%) felt their API documentation was “Very Good” while 33% of indicated their documentation was “Poor” or “Needs Improvements”.

    Earlier we identified obstacles to having up-to-date documentation was “Limited Time Due to Workload”. These findings combined convey obvious areas to improve.

    Methodology

    OpenAPI Specification is Used by Over One Third of Survey Respondents

    0%

    When it comes to managing documentation, the most common means to do so is by using an API definition like “OpenAPI to Automate API Document Creation” (36%) followed by “Manual Code Annotations Created by Developers” (26%). Almost one fifth of survey respondents told us they “Don’t Have an API Documentation Process in Place”; we hope to see improvement in years to come!

    Your Single Source of Truth
    Try SwaggerHub for Free Now!

    The SwaggerHub Integration For Confluence is Favored For Consumer Documentation

    0%

    Survey respondents were asked to select all the tools / ways they use to provide consumer-facing documentation.

    The “SwaggerHub Integration for Confluence”, released only six months prior to this survey launching, gained a lot of interest and comes out on top as the most favored tool (36%). “ReadMe” came in as the second most favored tool at 26%. Almost one fifth of respondents shared that they do not have a solution for consumer documentation.

    We hope that, like the cohort of respondents that shared they generally don’t have documentation (prior question), they are thinking about implementing it.