Swagger and OpenAPI Specification for documents

ElegantSpiceworks

Conclusions

The pages generated by the Swagger UI look pretty spartan and stand apart, at least visually, from the remaining documentation. Integration into existing online help requires a suitable redesign and major interventions. The information content also depends significantly on how extensively the provider specifies its service in the API description. Not least, the use of the Swagger UI pages is not always self-explanatory.

On the up side, the use of Swagger involves very little additional work, while facilitating access to the REST API for users or other developers. If you integrate the tools into your build process, you will benefit from constantly updated documentation, including a client SDK. Conversely, programmers can use Swagger to generate a client SDK quickly for a third-party REST API and save at least some typing. It could thus be worthwhile for all parties to take a look at Swagger and its associated tools.

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy ADMIN Magazine

SINGLE ISSUES
 
SUBSCRIPTIONS
 
TABLET & SMARTPHONE APPS
Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

  • Developing RESTful APIs
    The popularity of REST APIs has increased of late, not only on industry sites, but also in the framework of smaller projects. We explain why this is so and illustrate the fairly abstract architectural approach with a concrete example.
  • RESTful APIs in practice
    Internet providers often market their open interfaces as RESTful, but is this true of the APIs, especially when no standard exists? We introduce some REST providers and look at how closely their API architectures reflect the REST principle.
comments powered by Disqus