- (not translated) # Provides display of OpenAPI docs using the Swagger UI plugin.
- Drush AliasesStraightforward to set up if you have SSHaccess.Part of keeping your swagger.Anatomy of an alias file.(Cheater Demo Using Pantheon.)Thursday, May 23, 13 54. Thursday, May 23, 13 55. Deploying to ProdPush or pull areboth ok.Integrate this withversion control (e.g.tag it).Script, test,automate.Thursday, May 23, 13 56.
API providers describe their API’s functionalities with specifications and definitions, like OpenAPI/Swagger, RAML, API Blueprint, I/O Docs or WSDL. API documentation solutions convert these definitions into a structured, easy to use API documentation for developers.
Maintainers for Swagger. Mmillford - 8 commits. Last: 5 years ago, first: 6 years ago. View all committers. Thank you to these Drupal contributors.
API documentation tools are sometimes named after the type of definition they take, e.g. Swagger generates API documentation from Swagger definitions. They also often include the definition in their naming, e.g. RAML 2 HTML.
API documentation generators using the Swagger/OpenAPI specification
The Swagger specification is a powerful definition format that describes RESTful APIs. It maps all the resources and operations associated with a RESTful interface and makes it easier to develop and consume an API.
Recently the Swagger standard changed its name to Open API, you can find out more about the initiative at the Open API Initiative website. As a leading standard Swagger/OpenAPI has accumulated a large range of API documentation generators that use the specification format.
Swagger
Swagger is a complete framework for describing, producing, consuming, and visualizing RESTful web services.
Use the Swagger ecosystem to create your API documentation: document APIs with JSON using the Swagger spec, and use the Web UI to dynamically convert it into API documentation in a web page. Your API documentation will be displayed through the Swagger UI, which provides a well-structured and good-looking interface.
Example of an API documentation displayed with the Swagger UI
Swagger is free to use, licensed under the Apache 2.0 License. You can find all Swagger-related public tools under the swagger-api GitHub account.
Many open source projects and commercial vendors provide Swagger integrations, so make sure to check out the list of available solutions before building new tooling - there is a big chance you will find an existing solution that fits the needs of your project.
As today’s leading API ecosystem, it’s also the best documented and supported. Should you decide to document your APIs with Swagger, you can find plenty of resources, tutorials, examples and help online.
DapperDox
With DapperDox you can author readable guides and have them form part of a cohesive set of documentation along with the API specifications: You can inject relevant documentation into the rendered specification page.
To create your API documentation with DapperDox, point DapperDox at your OpenAPI/Swagger specifications, add some documentation in Markdown and let DapperDox do the rest.
ReDoc
ReDoc uses the OpenAPI specification and generates a responsive site with a three-panel design. It pulls markdown headings from the OpenAPI description field into the side menu, and supports deep linking.
ReDoc aims to make deployment extremely easy, provides a wide support for OpenAPI objects, and offers interactive documentation for nested objects. You can include code samples via a third-party extension.
API documentation generators using the RAML specification
RAML (RESTful API Modeling Language) helps you manage the whole API lifecycle from design to sharing.
RAML is built on broadly-used standards such as YAML and JSON, and is language neutral with tools for: Java, Javascript, .Net, PHP, Python, Ruby, etc.
To create your API documentation with RAML, you can choose open source tools like the API Console or RAML 2 HTML. Documentation can be generated quickly and on the fly. With parsers available for many languages you can create your own custom docs and interactive scripts like e.Pages and Spotify.
RAML 2 HTML
RAML 2 HTML is a simple RAML to HTML documentation generator with theme support, written for Node.js.
Example of an API documentation displayed with RAML 2 HTML’s default theme
RAML 2 HTML ships with a default theme, but you can install more from NPM. Dj logo maker online. For example, to render RAML to Markdown, you can install the raml2html-markdown-theme.
RAML Api Console
Using the RAML API Console you can create HTML documentation from a RAML specification. It allows browsing of API documentation and in-browser testing of API methods.
There are two ways you can include the console: directly, or within an iframe.
Example of an API documentation displayed with the RAML API Console
API documentation generators using the API Blueprint specification
API Blueprint is a Markdown-based document format for writing API descriptions and documentation. With API Blueprint you can quickly design and prototype APIs to be created, or document and test already deployed APIs.
Thanks to its broad adoption there is a wide range of tools built for API Blueprint. From various standalone tools such as mock server, documentation and testing tools to full-featured API life-cycle solutions.
Snowboard
Snowboard is an API Blueprint parser and renderer. It offers a colourful default theme illustrating API request types and responses, and can also be used with custom templates.
Example of an API documentation displayed with Snowboard
Aglio
Aglio renders HTML from API Blueprint files, with support for custom colors, templates and themes.
Example of an API documentation displayed with Aglio (Cyborg two-column theme)
Other free and open source API documentation generators
Besides the ones detailed above, there are plenty of different open source API documentation generators for different languages and API specifications. Here’s a brief summary of the ones we’ve explored:
- I/O Docs: I/O docs is an API definition format for the TIBCO Mashery network that comes with a live interactive documentation system for RESTful web APIs. By defining APIs at the resource, method and parameter levels in a JSON schema, I/O Docs will generate a JavaScript client interface.
- Slate: Slate helps you create responsive API documentation with a clean, intuitive design. Although it’s built in Ruby, when you write docs with Slate, you’re just writing Markdown, which makes it simple to edit and understand. By default, your Slate-generated documentation is hosted in a public Github repository, which makes it simple for other developers to make pull requests to your docs if they find typos or other problems. Of course, if you don’t want to use GitHub, you can also host your docs elsewhere.
- Whiteboard: A NodeJS based project started from Slate.
- apiDoc: Inline documentation for RESTful web APIs, that creates a documentation from API annotations in your source code.
- CUUBEZ API Visualizer: Java based API solution to visualize the documentation of RESTful web APIs. This API visualizing framework supports all JAXRS based java REST frameworks and non-JAXRS java based REST frameworks that are currently available in the industry.
- Apidox: XML powered live interactive API documentation and browsing for RESTful APIs.
- Carte: A simple Jekyll based documentation website for APIs. Designed as a boilerplate to build your own documentation, heavily inspired by Swagger and I/O docs.
- Docbox: A responsive website generated from Markdown documentation content. It’s dynamically updated with React.
And a free one:
- API Docs: Although not open source, API Docs provides a hosted public API documentation service for OAS (Swagger) and RAML specifications for free. Features like custom domains, themes, and analytics, are available for a nominal cost through the StopLight integration.
Although very handy, API documentation generators are not the only way to render and display your API docs. Many general purpose documentation tools can also get the job done. You could consider using them if you already have one in place, or if you have more documentation tasks than documenting your API alone.
A couple of documentation tools you can check out:
- Docco: Docco is a quick-and-dirty documentation generator. It produces an HTML document that displays your comments intermingled with your code.
- Doxygen: Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL, Fortran, VHDL, Tcl, and to some extent D. To document your API, generate an online HTML documentation browser or an offline reference manual, and configure Doxygen to extract the code structure from your source files.
We mentioned these tools to give you an idea of how you can use general documentation tools for API documentation, but there are many more to choose from, if you’d like to follow this approach.
Good API documentation is necessary, but not sufficient for a great developer experience, so it’s better to think about the whole experience in terms of a developer portal that will fulfill all developer needs. Besides the API documentation, a developer portal can include guides and tutorials, reference pages, FAQs, forums, other support resources, software development kits, etc. For an overview of all the different types of documentation a good developer portal needs, check our blog post series on developer portal components or receive it as a white paper in your mailbox by subscribing to our Developer Portal mailing list.
At Pronovix, we work with Drupal, an open source content management system to build a full-featured developer portal, a toolbox for developer relations with integrated API documentation.
Drupal has a couple of modules that you can use to document your APIs, one of which is the API module originally developed to produce the Drupal developer documentation available at api.drupal.org. It implements a subset of the Doxygen documentation generator specification, with some Drupal-specific additions. If you’d like to publish your API documentation and you plan to extend it into a developer portal, you could give Drupal a try, as it’s free, open source, and has extensive documentation both for the core CMS and the API module.
We have done extensive work with Apigee’s developer portal that is built in Drupal 7, and we are building a new developer portal in Drupal 8, Drupal’s latest release. As API documentation is a key requirement, it will include a custom API documentation generator that can import Swagger/OpenAPI files and that splits the documentation for individual endpoints into separate entities so that you can control access granularly and easily extend your documentation (especially important for partner portals and for organisations that have strong security requirements). Our ultimate goal is to share our developer portal package as an open source Drupal distribution.
As you can see, with some research and hopefully with the help of this post, you have a good chance to find an open source API documentation tool that fits the needs of your project.
Although this article features quite a few solutions, there are many others available or in development, and new ones are popping up continuously. Please let us know in the comments if you’ve tried a solution that you’d recommend to others!
Quick summary | Source (specification) | Live demo | |
---|---|---|---|
Swagger | Whole ecosystem, lots of integrations Good-looking UI for docs Widely used, many resources available | Swagger/OpenAPI | Swagger demo |
DapperDox | Inject relevant documentation right into the rendered specification page | OpenAPI, Markdown | DapperDox demo |
ReDoc | Easy deployment Wide support for OpenAPI objects Interactive, responsive documentation | OpenAPI | ReDoc demo |
RAML 2 HTML | Simple RAML to HTML documentation generator theme support | RAML, NodeJSwith | RAML 2 HTML demo |
RAML API Console | Browsing of API documentation and in-browser testing of API methods | RAML, NodeJS | RAML API Console demo |
Snowboard | API Blueprint renderer | API Blueprint | Snowboard demo |
Aglio | API Blueprint renderer with many custom themes | API Blueprint | Aglio demo |
I/O Docs | Live interactive API documentation system for I/O Docs specification format | I/O Docs (JSON) | I/O Docs demo |
Slate | Clean, intuitive design Write in Markdown Collaboration through GitHub | Markdown (Ruby) | Slate demo |
Whiteboard | NodeJS based Slate alternative | NodeJS | Whiteboard demo was from wifidistribution.com/docs, no longer available as of May 2019 |
apiDoc | Inline documentation for RESTful web APIs | NodeJS | apiDoc demo |
CuuBEZ API Visualizer | Visualize the documentation of RESTful web APIs | Java | CuuBEZ API Visualizer repo |
Apidox | XML powered live interactive API documentation and browsing for RESTful APIs | XML, PHP | Apidox demo |
Carte | A simple Jekyll based documentation website for APIs | Jekyll, YAML | Carte demo |
Docbox | A responsive website generated from Markdown documentation content | Markdown | Docbox demo |
API Docs | Free, hosted API documentation | OpenAPI, Swagger, RAML | API Docs demo |
Definitions
An Application Programming Interface (API) is a set of clearly defined methods of communication between various software components. Organizations share their APIs so that developers can build applications that use the services of their software.
API documentation describes what services an API offers and how to use those services. Good quality documentation is essential to developer experience, which in turn will impact the adoption and long-term success of an API.
We wrote this post for:
- API providers: To provide an overview of free and open source tools for companies that want to share, update or customize their API docs or developer portal.
- Developer portal builders: To provide an independent review of existing developer portal solutions that developer teams tasked with building developer portals can use as a reference in discussions with their clients, to make it easier to select the one that best fits their needs.
- Technical writers: To create a resource that tech writers can use to select the API documentation infrastructure that fits best with their existing authoring workflows.
I have noticed a recent change when asking for API documentation. It used to be the case that an API either had no documentation at all or had a massive tome that took weeks to write, was out of date before the ink was dry and never really read. In the last couple of years, however, the question has often resulted in the answer 'oh, we use Swagger for documentation, I'll send you a link'.
I decided to look into Swagger, see what it does, and how it can be used to document the Drupal JSON:API.
What Is Swagger?
Swagger is an API documenting tool that allows developers to quickly and easily generate the needed documentation for an API. This involves a specification language (called OpenAPI) and an interface that can be used to document and test the API endpoints (called Swagger UI).
The power of Swagger is that it doesn't require fundamental changes to your API, it only requires that the API returns a specification detailing all the things the API can do. This specification is the OpenAPI part of Swagger and includes things like what methods are available, what parameters those methods require, and details of any authentication that is required to use the API.
Swagger itself consumes this specification (which can be a static file) and presents it as an interactive interface.
![Drupal Swagger Drupal Swagger](/uploads/1/3/7/7/137789355/449270017.png)
This means that when someone says they have Swagger documentation, they mean their API has an OpenAPI compliant interface that is being consumed by Swagger. You can see an example of Swagger in action via their website.
Installing Swagger In Drupal
Getting Swagger UI installed into Drupal's JSON:API takes a few modules, so let's go through each of the modules you'll need.
JSON:API
Maybe an obvious one, but in order to document the core JSON:API in Drupal we first need to install it. This will create a large number of endpoints that allow you to interact with most parts of Drupal and will be the basis of the documentation we create.
OpenAPI
The OpenAPI module allows you to make your RESTful and JSON:API services discoverable using the OpenAPI standard. This can then be used by Swagger to generate the interactive documentation.
Out of the box, this module does nothing on a default install of Drupal. There are a couple of other modules we need to install to get the things we need.
OpenAPI for JSON:API
Drupal Jsonapi Swagger
This module will integrate the JSON:API module with the OpenAPI module so that we can expose the JSON:API as an interface that Swagger can use.
Once the module is installed along with the core JSON:API module it allows access to a page under the path /openapi/jsonapi?_format=json. On a default Drupal site this will show a large file containing all of the points of interaction that exist in the API. This is the file that gets used by Swagger to generate the interface.
As this file shows all of the interactions available on your site it will be of great interest to any attackers out there. This file falls under the same security policy as the JSON:API and as such will be inaccessible to anonymous users by default.
OpenAPI UI
The OpenAPI UI is a generic module that provides a way of interfacing between the OpenAPI interface and any third-party libraries we want to use. Using this module allows the Swagger UI to be viewed within the Drupal site itself and not as a separate interface. This has the added benefit of requiring a Drupal login in order to view the API documentation unless you relax the permissions on the interface.
Swagger UI For OpenAPI UI
Finally, we are now able to install the Swagger UI module. This ties everything together and allows us to view the Swagger interface within our Drupal site. This module has no configuration of it's own as it simply provides the bridge between OpenAPI and Swagger. It does, however, have a composer file that includes the Swagger tool itself and so installing the module by composer is a requirement.
Composer Require Commands
For ease of integration, I have collected together all of the composer commands you'll need into a single command here.
![Drupal swagger ui formatter Drupal swagger ui formatter](/uploads/1/3/7/7/137789355/459168659.jpg)
Once that's done you can install the modules using either Drush or within the Drupal site. Make sure you enable the JSON:API module as well as all of the OpenAPI and Swagger modules.
Including The Swagger UI Library
Php-swagger
Even with all of these modules installed we still aren't in a position to run Swagger, we first need to tell composer what to do with the Swagger library so that Drupal can use it.
Depending on your Drupal setup you may not have the needed composer libraries in place. To make sure you do you can install the composer/installers and mnsami/composer-custom-directory-installer libraries by requiring them into your project. These packages will move dependencies into the correct parts of Drupal so they can be picked up and used.
Next, we need to edit the composer.json file to add in a couple of lines of configuration.
This integrates with settings you should already have in your composer.json file. Python sleep 1 second. Just lookout for the installer-paths section in that file and add an additional line to the libraries configuration. The Swagger UI for OpenAPI module includes the swagger-api/swagger-ui library so we don't need to manually include that.
Remember to run 'composer install' once you have added this to update the Drupal site with Swagger.
Adding A Small Patch
Unfortunately, I had a little bit of trouble getting things working straight away. Even after including all of the needed modules and libraries I couldn't get the Swagger documentation to run correctly. As it turns out there is a small error in the OpenAPI for JSON:API module that requires a little patch at the time of writing. This hasn't made its way into the module as it is causing tests within the module to fail, but it sorted out my immediate issue and allowed the page to work correctly for me.
Add the following to your composer file.
With that patch in place, you can run composer install to update your codebase.
Swagger Documented Drupal JSON:API In Action
As you can see, it takes a little bit of effort to get everything running correctly, so let's start using Swagger.
Once everything is installed (and patched) you can start to view your JSON:API as a documented Swagger UI interface. If you now visit the path /admin/config/services/openapi you will see the following.
The only item in the list is the JSON:API module interface since that is the only API module we have installed and integrated with OpenAPI. The 'View/Download' button here will open the raw OpenAPI definition file (basically a big JSON file). This is the file that OpenAPI for JSON:API module creates and is consumed by Swagger to generate the documentation page.
Visiting the 'Explore with Swagger UI' button is where the magic happens and is what I have been building up to for the entire article. This will show the following screen. There is a lot of items on this page as the JSON:API is quite comprehensive so the image below only shows the top of the page containing the heading and the start of the block configuration section.
Clicking on any of the endpoints in the Swagger page will drill down into the detail of that request. For example, clicking on the /block/block JSON:API endpoint will show this in more detail.
This interface is a great way to explore the JSON:API and viewing this page you can probably see the extent of the API available in Drupal. There are lots of different endpoints that allow interaction with blocks, fields, comments, users, pages, media, taxonomy terms, and even parts of the JSON:API itself.
One of the best parts about Swagger is the 'Try it out' button on the right-hand side. This will add an 'Add item' to each of the parameters and an 'Execute' button to the end of the parameters list. Clicking on the execute button will issue a real request to your site and show you the output along with header information. You can add parameters to the request by using the 'Add item' buttons.
It's also nice to see the curl command along with the rest of the information.
Drupal 7 Swagger
This is brilliant! It's well worth persevering with the setup of these modules to get this page up and running.
Conclusion
Whilst some of these modules are still in the pre-release stage, they pretty feature-complete and mostly stable. I did have to install a single patch to get the Swagger page working fully, but after that, the modules worked very well. Seeing the full endpoints of the JSON:API in one place makes finding the right command and using it an easy task. The fact that you can also try the API endpoints out within the tool makes everything worth it. Whilst tools like Postman and Insomnia allow you to test APIs, having this functionality baked into the site is amazing.
Drupal Swagger Ui Formatter
Installing Swagger in your Drupal site will give you a lot of information on how to use and interact with the JSON:API. This is useful even if you have used the API and are looking for a handy reference guide.
Final thoughts
Whilst this documentation tool is powerful, I wouldn't recommend jumping in and installing Swagger on a production site unless that's what you really want. The JSON:API module will work perfectly fine without Swagger so it might be worth adding the OpenAPI and Swagger modules to your configuration splits so they are only active on your dev and staging sites.
If you are new to the JSON:API I would also highly recommend you install the JSON:API extras module. Out of the box the JSON:API module exposes a lot of the inner workings of Drupal, which you might not want to expose. Using the JSON:API extras module you can restrict the footprint of the API and only expose the parts you need to use. For example, the API allows access to your content filter formats, so it is possible a user could alter a filter format to allow malicious code to be injected into the content. A user could then simply add some content and create a problem for your users.
It should be noted that the OpenAPI standard is just that, a standard. As such, there are different products that integrate with this standard to create API documentation. One of these tools is ReDoc, which creates a documentation page with the same kind of interactivity that exists in the Swagger tool. If you want to give ReDoc a try then you'll be interested to learn there is a ReDoc for OpenAPI UI Drupal module that will integrate ReDoc into Drupal in the same way as I have described above.