---
title: "API doc course update: Re-architecting the OpenAPI spec tutorials to start with visual modeling tools first, then code"
date: 2020-04-28
description: "The new flow in the OpenAPI section looks like this:  As part of this new flow, I added an extensive Stoplight tutorial here: Create an..."
canonical_url: https://idratherbewriting.com/blog/api-docs-start-with-visual-first/
---
# API doc course update: Re-architecting the OpenAPI spec tutorials to start with visual modeling tools first, then code
[![](http://s3.us-west-1.wasabisys.com/idbwmedia.com/images/newuserflowopenapispec2.png)](https://idratherbewriting.com/learnapidoc/restapispecifications.html)

As part of this new flow, I added an extensive Stoplight tutorial here: [Create an OpenAPI specification document using Stoplight Studio’s visual editor](/learnapidoc/pubapis_openapis_quickstart_stoplight.html).

I think this new approach (visual first, then code) makes more sense for several reasons. Not only is this a walk-before-you-run type of approach, but the reality is that if your head isn’t buried all day in the OpenAPI spec, it’s hard to remember all the specification details. I work much more frequently with library-based APIs, mostly Android, than with REST APIs. When I shift back into REST API mode, I have to refresh my memory about many things.

My guess is that in several years, using a visual editor will be the norm anyway. Sure, some systems (like Linux) that let you operate entirely from the command line appeal to some people, but the visual manipulation of objects (e.g., Windows interfaces) turns out to be much more user-friendly and easy, and the easy model tends to win out.