Share your answer to the May Stoplight Community Chat 💬

(Taylor Barnett) #1

Every third Friday of the month, we’ll open up a question to the Stoplight community to discuss and learn from other community members. The questions will be about how your team or organization designs, tests, or documents APIs. Hopefully, we all have something to learn from each other. Plus, all participants get badges!

Let’s kick it off this week with this question:

What process does your team or organization use to create your OpenAPI documents?

For example, is there a team of people who make decisions around API design? Or do individual developers make suggestions or decisions? Do you practice design-first, then code? Or write the code-first?

Looking forward to hearing your responses!

(Marc) #2

Well Stoplight, at a high level, follows design first for our HTTP api :).

For any ticket that involves a a change to our HTTP API, the first subtask is to create or update the API design document associated with the change. We manage one design document per resource, as seen in the screenshot below:

These design changes are then reviewed by an architect and discussed with the developer in the Jira ticket itself. Once approved, the developer can begin implementation.

10,000 foot view, but that’s the basic flow that’s working well for us right now!

1 Like
(Helen Griffith) #3

Well, I’m the technical author for our company so my answer is from a writer’s perspective… I haven’t been writing API documentation for a considerable amount of time and it’s very different from ‘other’ types of documentation. I’m learning every day!

We are relatively new to Stoplight. We had a bunch of public-facing APIs for which we had documentation in a different tool. That tool was no longer supported and did not live up to our expectations anyway so we had to quickly find a new tool and that’s how we discovered Stoplight. SO, so far, we’ve migrated our existing documentation assets plus Swagger files into Stoplight and that’s our current experience of it. (We’ve ‘tweaked’ our Swagger files within Stoplight to use env.variables too.)

Longer term, I can’t imagine that our developers will use Stoplight to create the code itself. I think they will always want to write the code themselves (I’m not entirely sure what process they use) and leave the more user-friendly/documentation aspects to me! I’d love to properly educate them as to the importance of the documentation (i.e. the docs ARE the UI for the API—without docs, how can a user use the API? But, things take time… Rome wasn’t built in a day, etc.

I’m not entirely sure this answered your question, but I hope it is better than nothing!

1 Like
(Nicolas Tisserand) #4

Hello everyone,

In my company, we promote a design-first approach.
The design is made by both IT and non-IT people. It’s important because IT people are supposed to know RESTful rules and on the other hand non-IT people are supposed to know the business rules and the global strategy. Thus, it’s an important collaboration job.

So, the Swagger file is considered as the sole refence for the next steps of the process : documentation, implementation, testing…

Regarding to the implementation, we use the Swagger with external tools to generate a bunch of classes that will be directly integrated in the software framework of our company. Then it’s up to the developers to code what is really valuable without bothering of boilerplate code.

You can read more of our approach in this case study : https://stoplight.io/case-studies/arkea/

1 Like