🚀 New Release: API-Doc-Crafter just got sharper. Cleaner. Meaner.
Giving my little OpenAPI merging monster some upgrades.

It all started with a simple idea: merge OpenAPI specs from multiple repos.
Now? It transforms outdated Swagger specs to OpenAPI 3+, generates HTML pages with full navigation, and allows customization via config or env.

✨ SecurityRequirement deduplication - because why merge APIs if you can't also merge logic?

🧠 Custom metadata enrichment - inject your info, license, contact, and docs straight from config. No more excuses.

🔁 Better parser fallback - now tries more ways to read broken specs than your average intern in panic mode.

🎭 Variable substitution in outputs - ${variables} be gone. Use env or config, stay DRY, stay sane.

🧪 Tests expanded. HTML, JSON, YAML outputs covered like a nuclear bunker.

🧰 Powered by GraalVM, no reflection, blazing fast.
🐳 Native Docker builds.
🧼 Reflection config surgically trimmed. Less bloat. More edge.

Project: https://github.com/YunaBraska/api-doc-crafter
Happy crafting. And remember: if your docs aren't automated, they're probably lies.

#OpenAPI #Swagger #APIdocumentation #DevTools #GraalVM #Java21 #Docker #Automation #CleanCode #DevLife #APIDocs #OpenSource #DeveloperTools #coding #programming

"Let me be blunt.

If your startup offers APIs and you don’t have a portal, you’re lighting developer acquisition money on fire. 💵 🧯🚒

Here’s what a good portal actually does:

Shortens time-to-value: faster POCs, faster adoption.

Reduces support tickets: devs can find what they need.

Builds trust: your API feels stable, documented, and ready.

Increases conversion: when docs show how easy it is to integrate, not just tell.

Still sending PDF onboarding packets to partners?

C’mon, boo. 🥲"

https://www.quetzalliwrites.com/newsletters/developer-portals-dev-friendly-or-dev-frustrating

#DevPortals #DeveloperPortals #APIs #API #APIDocumentation #TechnicalWriter #TechnicalCommunication

"The accompanying diagram is intended to help you quickly decide how to document an API, but particularly a REST API. The first split is just to make sure you are looking for the right kind of API.

Here is some more context to help you decide on an approach and get started."

https://gist.github.com/briandominick/3ffab6be460fbde799aa34e0a42a4299

#API #APIs #APIDesign #REST #APIDocumentation #OpenAPI #DocsAsCode #TechnicalWriting #TechnicalCommunication

Do developers need code samples in API documentation?

https://idratherbewriting.com/blog/code-samples-might-not-be-needed-anymore

#APIDocumentation #TechWriting #CodeSamples #AI #DeveloperTools #SoftwareDocumentation #APIs #AIInTechWriting #DevDocs #TechnicalWriting #APIDocs #Coding #AIvsManual #SoftwareDevelopment

"Getting to this point isn’t unusual. Clients clearly think they’re making the call correctly, or else they would fix the endpoint themselves. Some misspellings are difficult to catch. The enum USER_RETREIVE may not be noticed from USER_RETRIEVE, especially if picking it from a list. Misspellings happen and they’re not always caught before making it to the contract. As an aside, that’s why it’s important writers routinely check development’s changes. This applies, too, to our testing calls in Postman, where manually entering endpoints and values are more pervasive.

The reason this isn’t caught is simple: We’re not expecting it.

For our testing, the call is made and we get results. We may even spot check some of them. But generally, results aren’t examined that closely. For instance, how often do you so carefully examine a returned list of 50 or 100 items? You check may check that the objects are complete but not that the list conforms to the search criteria.

The reason this happens is because of an intentional behavior on the server. This behavior is called Lenient Handling or Strict Handling."

https://robertdelwood.medium.com/understanding-query-parameter-handling-in-rest-calls-1821e0c3fa8c

#APIs #RESTAPIs #Rest #APITesting #APIDesign #APIDocumentation #SoftwareDevelopment

“Fortunately, I think there’s a good alternative to the dismal picture of brain-dead tech writers pressing buttons on AI machines and passing the content to SMEs for review. That alternative is to focus on what AI algorithms can’t do (at least not with a few button clicks). In this revised approach, tech writers offload the simple tasks to AI tools to fix while focusing their real time and energy on more complex, ambitious tasks that are beyond the straightforward capabilities of AI tools.

When I say beyond AI capabilities, I still mean AI tools might assist or augment tech writers in the work; it’s just that the tasks aren’t as simple as the mechanical tasks of fixing doc bugs that I described earlier (e.g., “what’s the issue? what’s the fix?”).

For example, when I set about creating complex tree diagrams showing all elements in an API, this was a new kind of documentation that hadn’t been done before at my company. It became an instant hit and one that proved challenging to maintain and grow and fix, but still worthwhile. (In fact, in a chat with a product manager last week, he wondered if our tree diagram page wasn’t the most popular page in our documentation.)

If we focused more on these sophisticated tasks (beyond click-button AI), I think tech writers could have a brighter future.”

https://idratherbewriting.com/blog/recursive-self-improvement-complex-tasks

#TechnicalWriting #SoftwareDocumentation #APIDocumentation #AI #GenerativeAI #LLMs #Docs

“A README acts as the front door to an API, offering consumers brief and sufficient information to get started. A full documentation is a place where consumers go to when they need to find information about any detail of the API. Having one doesn't mean you shouldn't have the other. But, having a README is, in my opinion, the very minimum you can do if you're serious about your API. And, at the very minimum, there are three elements I'd consider.”

#APIs #APIDocumentation #Markdown #TechnicalWriting #Git #DocsAsCode

https://apichangelog.substack.com/p/three-elements-of-a-good-api-readme

"A quick start guide offers concise step-by-step instructions to help users quickly get started with a product, service, or tool. In the context of API documentation, a quick start guide covers the minimal steps required for developers to make their first API call successfully. It typically provides steps such as how to create an account, where to locate API keys or credentials, how to authenticate, example code to make a basic API call, a way to display the response, and troubleshooting tips. The goal is to deliver a quick win to developers and provide a foundation to integrate with your API."

https://www.apimatic.io/blog/how-to-design-a-quick-start-guide-for-your-api

#TechnicalWriting #APIs #APIDocumentation #SoftwareDocumentation #GettingStarted #Tutorials #SoftwareDevelopment #DE #DeveloperExperience

"Normally, you don't visit your own API documentation that often, right? I mean, if you already know how your API works, why would you want to consult its documentation? Conversely, there's a place you visit—or should visit—very often, with information you care about your API. I assume you have an API dashboard where you can review metrics such as the ones I described earlier. Usually, the dashboard lives close to the API gateway, or somewhere where other company-wide observability tools reside. What I'm proposing here, in short, is that the API documentation can be the best place to present those metrics to you, the producer.

Being able to see the metrics you care about right near the documentation for each part of your API feels refreshing. You could, for instance, be looking at the reference of one operation and immediately see its usage trend, the error rate, the number of active consumers in the last hour, and so on. What's more, some of the information visible only to you could also be actionable. You could, for instance, open the pending support requests to see what the top complaints are. Or, you could immediately check why there's such a percentage of errors on one single operation.

While most information would be restricted to you, the producer, I argue that some things could even be openly shared with your API consumers. Imagine being a consumer and seeing a list of "popular" API operations right on the documentation. Or understanding if a certain operation is producing a high error rate. All these things could be easily available in the API documentation."

https://apichangelog.substack.com/p/producer-oriented-api-documentation

#TechnicalWriting #APIs #APIDocumentation #SoftwareDocumentation #APIMetrics #APIAnalytics #SoftwareDevelopment