--- title: Why We Use Swagger For API Documentation | Dreamfactory description: Nothing makes a REST API easier to use than good documentation. Well, nothing except maybe a live test environment right there in the documentation. image: https://blog.dreamfactory.com/hubfs/Imported_Blog_Media/swagger1.png --- [![DreamFactory logo](https://cdn.prod.website-files.com/64ed8da8a866be7a702fbae0/68d51994d3678214b54acb60_dreamfactory-navbar-logo.svg)](https://www.dreamfactory.com/) Products & Services [AI Data Gateway](https://www.dreamfactory.com/ai-data-gateway/overview) [Overview Why DreamFactory exists](https://www.dreamfactory.com/ai-data-gateway/overview) [Data Gov, Comp, Security Policy enforcement at the API layer](https://www.dreamfactory.com/ai-data-gateway/ai-data-governance) [Standard API Layer One contract for every backend](https://www.dreamfactory.com/ai-data-gateway/standard-api-layer) [API Gateway Functionality Routing, auth, rate limits, observability](https://www.dreamfactory.com/ai-data-gateway/api-gateway-functionality) [Deployment & Integration Self-hosted, cloud, hybrid](https://www.dreamfactory.com/ai-data-gateway/on-premise-deployment-and-integration) [Developer Productivity Auto-generated, never hand-coded](https://www.dreamfactory.com/ai-data-gateway/ai-development-accelerated) [AI App Architectures Patterns for RAG, agents, MCP](https://www.dreamfactory.com/ai-data-gateway/enterprise-ai-architectures) AI Data Models [AIOpenAI](https://www.dreamfactory.com/use-cases/openai) [GGoogle Gemini](https://www.dreamfactory.com/use-cases/google-gemini) [CAnthropic Claude](https://www.dreamfactory.com/use-cases/anthropic-claude-landing) [LMeta Llama](https://www.dreamfactory.com/use-cases/meta-llama) [MMistral AI](https://www.dreamfactory.com/use-cases/mistral) [CoCohere](https://www.dreamfactory.com/use-cases/cohere) Services and support [Quickstart Service Packages Expert-led Quickstarts to production](https://www.dreamfactory.com/services-and-support/quickstart-services-packages) API Management [Generate & Manage REST APIs From any database, in seconds](https://www.dreamfactory.com/api-management/generate-rest-apis) [Features Security, scripting, self-hosted & more](https://www.dreamfactory.com/api-management/features) [API Generation The complete guide to auto-generated APIs](https://blog.dreamfactory.com/a-complete-guide-to-api-generation) [API Management Concepts, tools, and best practises](https://blog.dreamfactory.com/what-is-api-management-a-brief-overview-of-api-management-concepts-and-tools?_gl=1*jl0njh*_gcl_au*MjQzMjgwMTc3LjE3ODIzMjI3MzY) Use Cases AI Use Cases [AI Data Access Secure, governed reads for your LLMs](https://www.dreamfactory.com/use-cases/ai-data-access) [MCP Server Drop-in Model Context Protocol](https://www.dreamfactory.com/use-cases/mcp-server) [Legacy Modernization Wrap mainframes with REST](https://www.dreamfactory.com/use-cases/legacy-modernization) [Data Governance Audit every call, enforce every policy](https://www.dreamfactory.com/use-cases/data-governance) [Customer Case Studies](https://www.dreamfactory.com/case-studies) [Energy Modernization](https://www.dreamfactory.com/case-studies/energy-snowflake-modernization) [Government Modernization](https://www.dreamfactory.com/case-studies/government-mainframe-oracle-modernization) [Government Business Intelligence](https://www.dreamfactory.com/case-studies/government-sql-server-bi-analyst-queries) [Manufacturing Modernization](https://www.dreamfactory.com/case-studies/steel-manufacturing-sap-erp-modernization) [Financial Services Investor Portal](https://www.dreamfactory.com/case-studies/financial-services-sql-server-investor-portal) [Non-Profit Partner Data Sharing](https://www.dreamfactory.com/case-studies/non-profit-sql-server-partner-data-sharing) [Professional Services Exec Dashboards](https://www.dreamfactory.com/case-studies/professional-services-erp-dashboards) [Education HR and External Data Sharing](https://www.dreamfactory.com/case-studies/education-student-hr-sql-server-mysql-external-data-sharing) Industries Industries #### [Healthcare HIPAA-grade APIs across EHR, claims, and labs.](https://www.dreamfactory.com/use-cases/healthcare) #### [Financial Services Portfolios, partners, and portals on one layer.](https://www.dreamfactory.com/use-cases/financial-services) #### [Government Modernize mainframes without re-platforming.](https://www.dreamfactory.com/use-cases/government) #### [Manufacturing SAP, MES, and shop-floor data, governed.](https://www.dreamfactory.com/use-cases/manufacturing) #### [Spotlight How enterprises run on DreamFactory From healthcare to energy to finance — governance baked into every endpoint. Browse case studies →](https://www.dreamfactory.com/case-studies) Connectors SQL Database [SQL SQL Server](https://www.dreamfactory.com/connectors/sql-server) [OR Oracle](https://www.dreamfactory.com/connectors/oracle) [PG PostgreSQL](https://www.dreamfactory.com/connectors/postgresql) [My MySQL](https://www.dreamfactory.com/connectors/mysql) NoSQL & Docs [Dy DynamoDB](https://www.dreamfactory.com/connectors/dynamodb) [Do DocumentDB](https://www.dreamfactory.com/connectors/azure-documentdb) [Mo MongoDB](https://www.dreamfactory.com/connectors/mongodb) [Cb CouchDB](https://www.dreamfactory.com/connectors/couch-db) Cloud Warehouses [S3 S3](https://www.dreamfactory.com/connectors/amazon-s3) [Ab Azureblob](https://www.dreamfactory.com/connectors/azure-blob) [FS FTP/SFTP](https://www.dreamfactory.com/connectors/ftp-sftp) [LS Local Storage](https://www.dreamfactory.com/connectors/local-storage) C & SaaS [Sf Salesforce](https://www.dreamfactory.com/connectors/salesforce) [API REST / SOAP](https://www.dreamfactory.com/connectors/soap-to-rest) [See all 30+ connectors](https://www.dreamfactory.com/connectors) [Blog](https://blog.dreamfactory.com/) [FREE 30 Minute Demo](https://www.dreamfactory.com/demo) [![DreamFactory logo](https://cdn.prod.website-files.com/64ed8da8a866be7a702fbae0/68d51994d3678214b54acb60_dreamfactory-navbar-logo.svg)](https://www.dreamfactory.com/) ![hamburger](https://blog.dreamfactory.com/hubfs/raw_assets/public/dreamfactory/images/megamenu/menu-hamburger.svg) ![close](https://blog.dreamfactory.com/hubfs/raw_assets/public/dreamfactory/images/megamenu/close-menu.svg) Back to main menu Products & Services Use Cases Industries Connectors [Blog](https://blog.dreamfactory.com/) [FREE 30 Minute Demo](https://www.dreamfactory.com/demo) [AI Data Gateway](https://www.dreamfactory.com/ai-data-gateway/overview) [Overview Why DreamFactory exists](https://www.dreamfactory.com/ai-data-gateway/overview) [Data Gov, Comp, Security Policy enforcement at the API layer](https://www.dreamfactory.com/ai-data-gateway/ai-data-governance) [Standard API Layer One contract for every backend](https://www.dreamfactory.com/ai-data-gateway/standard-api-layer) [API Gateway Functionality Routing, auth, rate limits, observability](https://www.dreamfactory.com/ai-data-gateway/api-gateway-functionality) [Deployment & Integration Self-hosted, cloud, hybrid](https://www.dreamfactory.com/ai-data-gateway/on-premise-deployment-and-integration) [Developer Productivity Auto-generated, never hand-coded](https://www.dreamfactory.com/ai-data-gateway/ai-development-accelerated) [AI App Architectures Patterns for RAG, agents, MCP](https://www.dreamfactory.com/ai-data-gateway/enterprise-ai-architectures) AI Data Models [AIOpenAI](https://www.dreamfactory.com/use-cases/openai) [GGoogle Gemini](https://www.dreamfactory.com/use-cases/google-gemini) [CAnthropic Claude](https://www.dreamfactory.com/use-cases/anthropic-claude-landing) [LMeta Llama](https://www.dreamfactory.com/use-cases/meta-llama) [MMistral AI](https://www.dreamfactory.com/use-cases/mistral) [CoCohere](https://www.dreamfactory.com/use-cases/cohere) Services and support [Quickstart Service Packages Expert-led Quickstarts to production](https://www.dreamfactory.com/services-and-support/quickstart-services-packages) AI Data Models [Generate & Manage REST APIs From any database, in seconds](https://www.dreamfactory.com/api-management/generate-rest-apis) [Features Security, scripting, self-hosted & more](https://www.dreamfactory.com/api-management/features) [API Generation The complete guide to auto-generated APIs](https://blog.dreamfactory.com/a-complete-guide-to-api-generation) [API Management Concepts, tools, and best practises](https://blog.dreamfactory.com/what-is-api-management-a-brief-overview-of-api-management-concepts-and-tools?_gl=1*jl0njh*_gcl_au*MjQzMjgwMTc3LjE3ODIzMjI3MzY) AI Use Cases [AI Data Access Secure, governed reads for your LLMs](https://www.dreamfactory.com/use-cases/ai-data-access) [MCP Server Drop-in Model Context Protocol](https://www.dreamfactory.com/use-cases/mcp-server) [Legacy Modernization Wrap mainframes with REST](https://www.dreamfactory.com/use-cases/legacy-modernization) [Data Governance Audit every call, enforce every policy](https://www.dreamfactory.com/use-cases/data-governance) [Customer Case Studies](https://www.dreamfactory.com/case-studies) [Energy Modernization](https://www.dreamfactory.com/case-studies/energy-snowflake-modernization) [Government Modernization](https://www.dreamfactory.com/case-studies/government-mainframe-oracle-modernization) [Government Business Intelligence](https://www.dreamfactory.com/case-studies/government-sql-server-bi-analyst-queries) [Manufacturing Modernization](https://www.dreamfactory.com/case-studies/steel-manufacturing-sap-erp-modernization) [Financial Services Investor Portal](https://www.dreamfactory.com/case-studies/financial-services-sql-server-investor-portal) [Non-Profit Partner Data Sharing](https://www.dreamfactory.com/case-studies/non-profit-sql-server-partner-data-sharing) [Professional Services Exec Dashboards](https://www.dreamfactory.com/case-studies/professional-services-erp-dashboards) [Education HR and External Data Sharing](https://www.dreamfactory.com/case-studies/education-student-hr-sql-server-mysql-external-data-sharing) Industries #### [Healthcare HIPAA-grade APIs across EHR, claims, and labs.](https://www.dreamfactory.com/use-cases/healthcare) #### [Financial Services Portfolios, partners, and portals on one layer.](https://www.dreamfactory.com/use-cases/financial-services) #### [Government Modernize mainframes without re-platforming.](https://www.dreamfactory.com/use-cases/government) #### [Manufacturing SAP, MES, and shop-floor data, governed.](https://www.dreamfactory.com/use-cases/manufacturing) SQL Database [SQL SQL Server](https://www.dreamfactory.com/connectors/sql-server) [OR Oracle](https://www.dreamfactory.com/connectors/oracle) [PG PostgreSQL](https://www.dreamfactory.com/connectors/postgresql) [My MySQL](https://www.dreamfactory.com/connectors/mysql) NoSQL & Docs [Dy DynamoDB](https://www.dreamfactory.com/connectors/dynamodb) [Do DocumentDB](https://www.dreamfactory.com/connectors/azure-documentdb) [Mo MongoDB](https://www.dreamfactory.com/connectors/mongodb) [Cb CouchDB](https://www.dreamfactory.com/connectors/couch-db) Cloud Warehouses [S3 S3](https://www.dreamfactory.com/connectors/amazon-s3) [Ab Azureblob](https://www.dreamfactory.com/connectors/azure-blob) [FS FTP/SFTP](https://www.dreamfactory.com/connectors/ftp-sftp) [LS Local Storage](https://www.dreamfactory.com/connectors/local-storage) C & SaaS [Sf Salesforce](https://www.dreamfactory.com/connectors/salesforce) [API REST / SOAP](https://www.dreamfactory.com/connectors/soap-to-rest) [See all 30+ connectors](https://www.dreamfactory.com/connectors) [![back arrow](https://blog.dreamfactory.com/hubfs/raw_assets/public/dreamfactory/images/orange-arrow.svg) Blog](https://blog.dreamfactory.com/) # Why We Use Swagger For API Documentation | Dreamfactory by Terence Bennett ![calendar icon](https://blog.dreamfactory.com/hubfs/raw_assets/public/dreamfactory/images/calendar-icon.svg) July 6, 2018 Table of contents RECOMMENDED ARTICLES - [A Complete Guide to API Generation](https://blog.dreamfactory.com/a-complete-guide-to-api-generation) - [10 Best API Management Tools](https://blog.dreamfactory.com/what-is-api-management-a-brief-overview-of-api-management-concepts-and-tools) - [Creating a Microsoft SQL Server API in Less Than 5 minutes with DreamFactory](https://blog.dreamfactory.com/creating-a-microsoft-sql-server-api-in-less-than-5-minutes-with-dreamfactory) - [Hasura vs. DreamFactory: A Comprehensive Comparison](https://blog.dreamfactory.com/hasura-vs-dreamfactory) - [Build A Snowflake REST API in Less Than 5 Minutes](https://blog.dreamfactory.com/generate-a-snowflake-rest-api-in-less-than-5-minutes) Nothing makes a REST API easier to use than good documentation. Well, nothing except maybe a live test environment right there in the [API documentation](https://www.dreamfactory.com/features/api-documentation/). And help with generating client side code to use your API would be awesome too. Come to think of it, having the documentation and test environment dynamic enough to update as you on-board more services would be a major plus. Well, you get all that and more with the latest DreamFactory DSP REST API with Swagger. ## **What is [Swagger](https://developers.helloreverb.com/swagger/)? ** Because REST APIs are not auto-discoverable, it was historically difficult if not impossible for fellow developers to understand API behavior (endpoints, input parameters, output values, etc) barring the availability of custom documentation or access to the API source code. This all changed with the advent of [Swagger](https://swagger.io/docs/specification/2-0/what-is-swagger/). Provided with a JSON/YAML specification defining your API structure, Swagger can create interactive API documentation, generate client libraries in many different programming languages, and more. ## Why We Use Swagger We wanted our REST API, and that of any added web services, to be easy to understand, quick to test, and simple to use right out of the box. The Swagger framework solves our server, client, documentation and testing sandbox needs, all in a language-agnostic [specification](https://github.com/wordnik/swagger-core/wiki), with plenty of open-sourced server and client side resources already available to help with generation. It also comes with an open-sourced front end, the [Swagger UI](https://github.com/wordnik/swagger-ui) framework, which quickly allows developers to work with the API, giving them a clear picture of how the API responds to requests with various parameters and options. It helps us to provide what a developer needs to get an app up and running with powerful web services with little time and effort. The interactive documentation is incredibly useful, as developers are provided with a web interface which allows for easy experimentation with the underlying API. The following example depicts DreamFactory's Swagger UI integration for a MySQL API. The user can set one or more of the many API parameters available for this particular endpoint (retrieve records from a table), identify the table name, and when the Execute button is pressed, the response will be output in JSON format. ![](https://blog.dreamfactory.com/hubfs/Imported_Blog_Media/swagger1.png) ## **How DreamFactory Generates API Documentation with Swagger** Documenting static services of our API is as easy as [annotating server-side code](https://github.com/wordnik/swagger-core/wiki/Downloads), just as you would use javadoc or phpdoc. You define the API services, including path variables, query parameters, and even members of the posted body data, along with models of any data types passed between client and server. Documentation is then easily generated in various formats (json, xml, etc) and cached for speedy access from clients. We then [generate client-side code](https://github.com/wordnik/swagger-codegen) from the resulting documentation for our API. We use this generated code in our apps, as well as, presenting them as SDK jump-starters for app developers using our platform. At DreamFactory, we added a little twist by allowing web services to be added or removed dynamically. For any non-native service that is added to your platform's API, a json or xml Swagger document meeting the specification can be added and/or modified to define that service, immediately making it testable from the included Swagger UI framework and usable by client-side generated code. ## **Using Swagger Documentation with DreamFactory** The easiest way to learn more about how DreamFactory's Swagger integration works is by spinning up a free (no credit card required) 14 day trial at [https://genie.dreamfactory.com/register](https://genie.dreamfactory.com/register). Alternatively, you can download a free on-premise version of the platform [via the DreamFactory website](https://www.dreamfactory.com/downloads-interstitial). If you'd like to trial a commercial version of the platform, or just have questions, [schedule a quick call with our team](https://www.dreamfactory.com/demo/)! TAGS: [API Management,](https://blog.dreamfactory.com/tag/api-management-2) [Services,](https://blog.dreamfactory.com/tag/services) [REST,](https://blog.dreamfactory.com/tag/rest) [Data Sources,](https://blog.dreamfactory.com/tag/data-sources) [SOAP](https://blog.dreamfactory.com/tag/soap) ![Terence Bennett](https://blog.dreamfactory.com/hs-fs/hubfs/1624046620145.jpg?width=100&height=100&name=1624046620145.jpg) Terence Bennett Terence Bennett, CEO of DreamFactory, has a wealth of experience in government IT systems and Google Cloud. His impressive background includes being a former U.S. Navy Intelligence Officer and a former member of Google's Red Team. Prior to becoming CEO, he served as COO at DreamFactory Software. Stay Connected with The Connector Newsletter! Subscribe to stay up-to-date with DreamFactory's latest product updates, API best practices, and tech humor in your inbox. [![Dreamfactory Logo](https://blog.dreamfactory.com/hubfs/raw_assets/public/dreamfactory/images/megamenu/Megamenu-logo.svg)](https://www.dreamfactory.com/) [Call Sales +1 (415) 993-5877](tel:+14159935877) Open – Mon–Fri 9–5 PT [FREE 30 Minute Demo](https://www.dreamfactory.com/demo) #### Follow us - [GitHub](https://github.com/dreamfactorysoftware/dreamfactory) - [Facebook](https://www.facebook.com/dfsoftwareinc/) - [X (Twitter)](https://twitter.com/dfsoftwareinc) - [LinkedIn](https://www.linkedin.com/company/dreamfactory-software) - [YouTube](https://www.youtube.com/c/dreamfactorysoftware) ### Features [Features](https://www.dreamfactory.com/features) [Self hosted](https://www.dreamfactory.com/features#self) [API Generation](https://www.dreamfactory.com/features#api) [Security](https://www.dreamfactory.com/features#secure) [Customization](https://www.dreamfactory.com/features#custom) [Pricing](https://www.dreamfactory.com/pricing) ### Installers [Linux](https://www.dreamfactory.com/features#installer) [Docker](https://www.dreamfactory.com/features#installer) [Kubernetes](https://www.dreamfactory.com/features#installer) ### API Resources [Documentation](https://docs.dreamfactory.com/) [Case Studies](https://www.dreamfactory.com/stories) [White Papers](https://www.dreamfactory.com/resources/whitepapers) [Academy](https://www.dreamfactory.com/academy) [API Calculator](https://calculator.dreamfactory.com) [Open Source](https://github.com/dreamfactorysoftware) ### Company [Blog](https://blog.dreamfactory.com/) [Hub](https://www.dreamfactory.com/hub) [About us](https://www.dreamfactory.com/about) [Partners](https://www.dreamfactory.com/partners) [Support](https://www.dreamfactory.com/support) [Connectors](https://www.dreamfactory.com/connectors) [Contact Us](https://www.dreamfactory.com/demo) © 2025 DreamFactory. All rights reserved. [Terms of Use](https://www.dreamfactory.com/terms-of-use) [Privacy Policy](https://www.dreamfactory.com/privacy-policy) [LLMs](https://www.dreamfactory.com/llms.txt) ```json { "@context" : "https://schema.org", "@type" : "BlogPosting", "author" : { "@type" : "Person", "name" : "Terence Bennett", "url" : "https://blog.dreamfactory.com/author/terencebennett" }, "dateModified" : "2024-06-26T06:22:42.931Z", "datePublished" : "2018-07-06T11:19:26.000Z", "headline" : "Why We Use Swagger For API Documentation | Dreamfactory", "image" : [ "https://blog.dreamfactory.com/hubfs/Imported_Blog_Media/swagger1.png" ], "mainEntityOfPage" : { "@id" : "https://blog.dreamfactory.com/why-we-like-swagger-for-api-docs", "@type" : "WebPage" }, "publisher" : { "@type" : "Organization", "logo" : { "@type" : "ImageObject", "url" : "https://blog.dreamfactory.com/hubfs/DreamFactory%20-%20Orange%20-%20Transparent-1.png" } } } ```