At MongoDB, we now generate REST API references for MongoDB Atlas from annotations in the product’s source. Our team’s writers proposed, planned, led, and implemented this project–and learned a lot along the way. We’ll share how we got buy-in from engineering and product stakeholders, coordinated the project across teams, implemented swagger-core annotations in Java, and drove positive change to benefit our team, the company, and our users.

1. John Williams
Lead Technical Writer, Cloud
MongoDB
Melissa Mahoney
Lead Technical Writer, Cloud
MongoDB
Annotate,
Automate,
& Educate
26 October 2022
Driving generated
OpenAPI documentation
to benefit everyone

2. Agenda
What problems were we trying to solve?
Getting buy-in and coordinating across
teams
Our implementation
Lessons we learned
What’s next?
Q&A

3. What problems
were we trying
to solve?

4. …documented by hand.
44
Resources
220
Endpoints
~3k
Parameters

5. What problems were we trying to solve?
Users noticed that docs
weren’t always updated
when APIs changed
Out-of-date docs
Code as the ultimate
source of truth to
describe how our APIs
work
Code is canon
Enable writers to work
on impactful content
Empower writers

6. With OpenAPI
1. Cloud codes.
2. Cloud gives info to Docs.
3. Cloud releases API code.
4. Docs writes API docs.
5. Cloud reviews API docs.
6. Docs publishes API docs.
API docs eventually consistent
with API code publicly.
Before OpenAPI
1. Cloud codes and annotates docs.
2. Docs reviews language.
3. Cloud releases API code.
4. API Docs published automatically.
API docs near immediately
consistent with API code publicly.

7. Getting buy-in
and coordinating
across teams

8. #BUILDTOGETHER
Partner with
engineering
Use familiar processes
Big changes can cause
uncertainty; use existing
processes to spread information.
Join a company initiative
Tie your work and its impact
directly to business goals.
Commit to support
Let your cross-team partners
know you’re not disappearing
after the initial push is complete!

9. Demonstrate value – for everyone
Spend more time on
high-impact content
that requires a human
touch
For writers
Test against the spec,
generate changelogs
and client libraries
For engineering
Accurate, interactive,
always-up-to-date API
docs
For users

10. Communicate!
4
Proofs of concept
7
Scopes & specs
35+
Approvers

11. #BUILDTOGETHER
… and then communicate more.
Wiki pages Presentations Office Hours
Slack Channel

12. Our
implementation

13. Scraper Script

14. Before editing After editing

15. ETL phase and generating annotation blocks
@Operation(
summary = "Return One Project",
operationId = "returnOneProject",
description =
"Returns details about the specified project. Projects group ...",
tags = {"Projects"},
parameters = {
@Parameter(
name = "userId",
description = "Unique 24-hexadecimal string that identifies...",
in = ParameterIn.PATH,
schema =
@Schema(
type = "string",
minLength = 24,
maxLength = 24,
pattern = OpenApiConst.OBJECT_ID_REGEX),
required = true)
}
responses = {
@ApiResponse(
responseCode = "200",
description = "OK",
content =
@Content(
mediaType = "application/json",
schema = @Schema(implementation = ApiAtlasGroupView.class))),
@ApiResponse(responseCode = "404", ref = "notFound"),
@ApiResponse(responseCode = "400", ref = "badRequest"),
@ApiResponse(responseCode = "500", ref = "internalServerError")
})

16. BACKFILL
For each resource,
writers pasted in
annotation blocks
Don’t break the
build
Ensure accuracy
and completeness
Seek PR approval
from engineering

17. Then we published!

18. Hand-off to
engineering

19. With OpenAPI
1. Cloud codes.
2. Cloud gives info to Docs.
3. Cloud releases API code.
4. Docs writes API docs.
5. Cloud reviews API docs.
6. Docs publishes API docs.
API docs eventually consistent
with API code publicly.
Before OpenAPI
1. Cloud codes and annotates docs.
2. Docs reviews language.
3. Cloud releases API code.
4. API Docs published automatically.
API docs near immediately
consistent with API code publicly.

20. Lessons we
learned

21. It was a journey.
Proof of Concept
A writer and an
engineer collaborate
on a basic PoC during
Skunkworks, planting
the seed.
Summer
2017
Spring
2020
Fall
2020
Summer
2021
Winter
2021-2022
Summer
2022
Research
An engineer
undertakes a research
spike for
implementation in the
codebase, and several
writers perform a
copy audit of existing
API docs.
More Proofs of
Concept
Several writers
annotate ~10
endpoints of varying
complexity within the
codebase to
demonstrate viability.
Annotations
required in code
The engineering team
implements code
checks that require all
new endpoints to have
annotations.
Annotations
complete
The writing team adds
annotations for all
existing endpoints.
OpenAPI docs
published
All engineering teams
and the writing team
test the OpenAPI docs
to ensure accuracy.
The OpenAPI docs are
published.

22. COMMUNICATION COORDINATION
Define specific
milestones
Raise awareness
early and often

23. AUTOMATION COMPATIBILITY
Code might need
to be refactored
Don’t automate
everything

24. Be the change.

25. Whatʼs next?

26. Whatʼs next?
Generate SDKs API tutorials Add more annotations

27. Q&A

28. Thank you for
your time.