API Documentation Software
An API isn't complete without companion documentation, and these days Swagger is widely considered to be the de facto API documentation format. DreamFactory will automatically create a complete set of interactive Swagger documentation alongside all generated APIs, ensuring your development team can quickly learn about the API endpoints. You'll gain several advantages from this approach:
- The documentation is always up-to-date, ensuring your team isn't frustrated by incomplete, outdated, or nonexistent reference material.
- Developers lacking DreamFactory administrative privileges are restricted to documentation perusal, ensuring sensitive API configurations can't be inadvertently or maliciously modified.
- When working with remote or scripted APIs, DreamFactory allows you to import OpenAPI specifications. You can obtain these specification documents from the third-party API vendor or create them yourself using a tool such as Stoplight.
Interactive API Docs for Every Data Source
Swagger documentation is interactive, meaning you can learn about the API by actually submitting API calls through the documentation interface. DreamFactory generates a list of documented API endpoints (the below screenshot presents an abbreviated list of endpoints generated for a Microsoft SQL Server database), and you can peruse the list and click on one to learn more:
For instance,clicking on the "Retrieve one or more records" endpoint opens up an interface that presents a list of all supported API parameters. In the case of this particular endpoint, you can identify the database fields you'd like returned, specify table joins, filter records, and limit, offset, and order results (see below screenshot).
After specifying any desired parameters, including the target table name, you'll be able to view the results of the API query directly within the documentation:
API Documentation Powered by Swagger
Swagger is an open source tool that helps developers design, build, and document REST APIs. Created at a time when there was no standardized solution for describing REST APIs in a machine-readable manner, Swagger eloquently solved this problem in such a way that in the ensuing years companies such as Google, Microsoft, and IBM adopted it within their own products.
More Resources for API Documentation
There are several useful online resources for learning more about API documentation, including: