Generating API Documentation from Code with Stoplight

When planning and designing an API two of the key ways to go about it are:

• Design First – Creating API descriptions like OpenAPI or JSON Schema in machine readable formats, either by hand, or using visual designers like Stoplight Studio, so create mocks and docs before writing any code.
• Code First – Using code annotation libraries like go-swagger, Springfox, or NSwag to add API-specific metadata to your source code, which can then be used to generate simple reference documentation.

The design-first workflow has been growing in popularity over recent years thanks to improvements in the tooling space, and the many benefits it provides organizations, like using mocking to unblock teams, almost free contract testing, speeding up coding of things like server-side validation, and the easy creation of high quality interactive reference documentation.

That said, we know there is more than one way to peel a turnip, and code-first is an important part of many API developers lives. Some tooling is built to only support one or the other workflow, but with Stoplight you can use code-first, design-first, or even a combination of both, with different teams at the same organization using whichever feels the most appropriate for their needs!

Stoplight Platform lets organizations create workspaces, and add projects that can come in two different flavours:

• Git Projects – Hook projects up to a Git repository, and webhooks will let Stoplight know when it should analyze new changes (pull requests merged, commits pushed to branches, etc.)
• Local Projects – Use Stoplight CLI to analyze the contents of a directory directly, either in Continuous Integration or anywhere else a CLI runs.

That last one is the ticket for code-first folks. Instead of needing the raw OpenAPI to live in a repository (and be manually edited by developers, or updated before committing) you can run extra commands, like exporting OpenAPI from your source code.

Exporting Annotations

Most folks working with the code-first workflow are using annotations, so we can export them to OpenAPI JSON/YAML to use OpenAPI without tooling needing to be aware of that specific annotation framework.

Let’s use PHP as an example, and specifically the swagger-php annotation framework.

First we can use Composer to install the tool globally.

composer global require zircote/swagger-php

To try out an example of swagger-php without having to create any code yourself, lets use the examples found in the swagger-php repo under Examples/ folder. There are several examples, but let’s look at petstore-3.0 as it’s a pretty common example.

git clone git@github.com:zircote/swagger-php.git

Taking a look at one of the example files in there, you’ll probably see annotations that look like this:

class Pet
{
    /**
     * Add a new pet to the store
     *
     * @OAPost(
     *     path="/pet",
     *     tags={"pet"},
     *     operationId="addPet",
     *     @OAResponse(
     *         response=405,
     *         description="Invalid input"
     *     ),
     *     security={
     *         {"petstore_auth": {"write:pets", "read:pets"}}
     *     },
     *     requestBody={"$ref": "#/components/requestBodies/Pet"}
     * )
     */
    public function addPet()
    {
    }

Instead of having OpenAPI in JSON or YAML files, it lives somewhere near the code responsible for handling the API logic it’s trying describe, with the hope being that its proximity will lead to developers keeping things up-to-date as they make changes to the code.

To export it, we can use this command:

openapi swagger-php/Examples/petstore-3.0 -o reference/swagger-php-petstore.yaml

Publishing can be done with the Stoplight CLI.

$ npx @stoplight/cli push -d reference/ --url https://code-first-examples.stoplight.io --ci-token {project-token}

Analyzing directory /Users/phil/src/code-first-examples/reference

Found 1 APIs
      19 Endpoints
      6 Models
      0 Articles
      0 Table of Contents

Calculating changes since last publish...

Found 26 Additions
      0 Modifications
      0 Deletions

Publishing changes to the master branch for project swagger-php!

success Pushed!

Now that’s been published up to the workspace https://code-first-examples.stoplight.io/ in a project called swagger-php.

To learn more about publishing, from the CLI or various other approaches, check out the automatic publishing documentation.

Summary

Thanks to this approach, your entire organization could have different folks using entirely different stacks, and you’d still have one consistent platform for their interactive API documentation.

Some projects can use PHP with swagger-php to annotate their source code, another project use Java with springdoc-openapi, or any of the other OpenAPI annotation frameworks for various other languages.

Some teams could use the full design-first workflow with Stoplight Studio, leverage all the handiness of automated style guides, mocking and design libraries, to make their next API better quality, more consistent, and quicker to production, yet still automatically put their docs in the same place as the other teams using the code-first approach.