How do you document your APIs?

Well documented APIs enhance the experience for developers and have become an essential requirement for defining an API's success. Good documentation is no longer just about clarity of the prose but also improving the affordance of documents as live API experiences for developers. As a result, there are a variety of tools targeted at API producers to automate the process of generating richer documents that reduces costs and time and dramatically improves developer adoption.

Given the fact that APIs are becoming the face of businesses and that documentation plays such a vital role in its adoption, we want to know which of these tools you are using or intend to use and your opinion on their relative relevance:

  • Swagger - A specification and complete framework implementation for describing, producing, consuming, and visualizing
    RESTful web services. Swagger is language agnostic.
  • Mashery I/O Docs- Mashery I/O Docs uses a JSON schema to describe APIs resources, methods and parameters.
    The schema is extensible.
  • Apiary.io - API blueprints are specified using a specialized Markdown syntax to get documentation up and running.
  • MuleSoft API Designer & Console - API Designer and API Console are RAML based tools.
  • Apigee Console To-Go - An interactive console defined using WADL and Apigee specific extensions to the WADL spec.
  • ASP.NET API Explorer - IApiExplorer is an abstraction layer that allows you to obtain a description of the structure of your
    Web APIs. ApiExplorer is the default implementation of IApiExplorer that inspects the routes and other Web API
    constructs to produce the description. This feature is currently available as part of our ASP.NET Web API project
    on CodePlex.
  • Docco - Docco produces an HTML document that displays your comments intermingled with code. All prose is passed throughMarkdown, and code is passed through Highlight.js syntax highlighting.
  • Dexy - Dexy is a general purpose documentation tool that supports any language and could also be used for documenting
    Web APIs.
  • Doxygen - Doxygen is also a general purpose documentation tool that can be used for documenting APIs too.
    It generates either an on-line documentation browser (in HTML) and/or an off-line reference manual from documented
    source files.
  • TurnAPI – TurnAPI is a text-to-HTML conversion tool for web writers that is based on markdown standards.
  • Enunciate: Enunciate is an open-source documentation generation engine that is attached to the Java build process to
    generate HTML documentation.
  • MireDot: MireDot combines data from various Java frameworks such as JavaDocs, Jax-RS, Jackson etc to
    generate documentation.
  • sphinxcontrib.httpdomain: sphinxcontrib.httpdomain is an extension to the general purpose documentation tool
    Sphinx for Python and C/C++. It generates documentation for RESTful APIs and has additional modules for supporting
    frameworks such as flask, bottle etc.
More at infoq. 

Σχόλια

Δημοσίευση σχολίου

Δημοφιλείς αναρτήσεις από αυτό το ιστολόγιο

One day at the WS-REST workshop in Florence

Εικόνα
I am really excited to write this article. I indeed had a wonderful time participating both as a presenter as well as an attendee for my first ever  ws-rest  workshop which is collocated each year with the famous WWW conference . The program was full of interesting topics, regarding (what else) discussions about REST practices, research and new ideas. I am borrowing its description here! Web APIs for a Web in evolution The Web is changing at a tremendous speed, and Web APIs play an important part in that. In fact, the number of Web APIs is growing so quickly that we face many challenges. The WS-REST workshop series aim to connect Web researchers and engineers to tackle the issues we are facing. Many of them are not solved by far: How to dynamically integrate Web APIs? How to create intelligent clients for Web APIs? How can we deal with the enormous growth and diversity? Session 1 First, to kick start the session,  Erik Wilde  had the floor for a super interesting k
Read more

PyAPI: A python library to play with various API Standards, like Hydra, Swagger, RAML and more

Εικόνα
Ever been in a situation where your manager asks you to write documentation for the APIs that you developed? Let’s face it, if you’re like most developers, you love to code and hate to write. Furthermore, writing takes time away from critical tasks you need to do, such as feature development and bug fixing. It’s no surprise that API documentation often ends up being frustrating and confusing for the reader—it rarely gets the attention it deserves. Hopefully nowadays there are many nice tools to document your APIs .  Why Document Your APIs? Let’s start with the non-technical side of the issue. API documentation has been around ever since the first programming languages were created. There’s been plenty of time to develop effective processes for creating quality documentation, yet well-written API documentation is still quite rare. Why doesn’t it happen? First, documentation is seldom prioritized. Even though it has a large impact on how much a software platform is adopted,
Read more

What is the Semantic Web?

The Semantic Web is an idea of World Wide Web inventor  Tim Berners-Lee  that the Web as a whole can be made more intelligent and perhaps even intuitive about how to serve a user's needs. Berners-Lee observes that although  search engine s index much of the Web's content, they have little ability to select the pages that a user really wants or needs. He foresees a number of ways in which developers and authors, singly or in collaborations, can use self-descriptions and other techniques so that context-understanding programs can selectively find what users want. Web 2.0 Is Not the Semantic Web Web 2.0 is all about people. It's a social thing. The second generation of the World Wide Web is focused on the ability for people to collaborate and share information online. Where the Web contains static  HTML  pages, Web 2.0 is  dynamic , in that it serves applications to users and offers open communications with an emphasis on Web-based communities. Web 2.0, because it focu
Read more