Generating an API README with AI
Is AI capable of generating a good-quality API README?
It's better not to have a README than to have a bad one. A bad README can destroy the reputation of any API. If you're like many API producers, you never have enough time to dedicate to your README. How can you then automate the creation of content using AI? Will it produce a good-quality README, or will it embarrass you? Read more to find out what the options are.
This article is brought to you with the help of our supporter, Scalar.
Scalar is the modern OpenAPI platform for the entire API lifecycle. Govern APIs with Scalar Registry, test offline with their built-in Client, generate beautiful documentation, and ship SDKs instantly - all from your single source of truth.
Forget about your API README. That is, if what you want to create is a low-quality, badly written document that doesn’t provide what potential API consumers need. You see, “a README acts as the front door to an API,” I wrote in February 2025, “offering consumers brief and sufficient information to get started.” It shouldn’t then be that hard to write a good README, should it? Well, it’s not as simple as it sounds. A good README needs to have at least three sections: an overview of the API, a “getting started” section, and information about the most important operations. While a good AI system can probably figure out the first and second sections, how would it know what the most important operations are? That’s where you, the API producer, need to come in. The AI needs your help! But, before we get there, let’s first see how an AI system can generate an overview of the API and an explanation about how to start using it.
To have an AI generate an overview of your API, you first need to already have a full reference. I know, that sounds like an oxymoron. But, if you think about it, it makes sense. An API overview is a summary of what the API is and what consumers can do with it. One easy way to have your API overview is to ask the AI to summarize an OpenAPI document. If you use a different kind of API specification (AsyncAPI, for instance), you can also use it, don’t worry. Here’s a prompt you can use right now to do the job for you:
You are an API product writer creating a README for a public-facing API that does not yet have documentation.
Using the provided OpenAPI specification as the source of truth, write the Overview section of the API README.
Explain what the API does in product and business terms, describe its main capabilities and use cases, and frame resources as real-world concepts.
Emphasize design principles and who the API is for. Do not list endpoints or include code examples. Write for external developers and product teams.
This is the OpenAPI document: https://example.com/openapi.yamlReplace that OpenAPI URL with one that works, try the prompt using your favorite AI chat, and let me know how it worked. I tested it using three different AI chat products, and the results were satisfactory. I mean, I wouldn’t fully automate this process. Instead, I’d use it to generate the overview, and then I’d probably do some minor edits here and there. And I guess I’d do the same with the “getting started” section. But this time, the AI needs specific information from the OpenAPI document. Getting started often involves signing up, getting API credentials, and using the right type of authorization. You need to make sure your OpenAPI document has all that information. Otherwise, there’s no prompt that will help you. Something else that will make getting started easier is marking one or more operations as good starting points for first-time consumers. One simple way to do that is to use OpenAPI tags. Create an OpenAPI tag named getting-started and add it to the relevant operations. Then, instruct the AI to use that tag to identify the right operations.
Now, finally, back to the challenge of generating the third section of the README: information about the most important operations. I’m sure you’re already thinking about how that can work using the techniques you’ve just seen before. The first thing you need to do is to add proper tags to all the OpenAPI operations. But don’t fall into the trap of using the important tag to mark the operations you feel are important. Instead, create tags that identify use cases and associate them with the right operations. So, for example, you could have the payment tag and use it in all payment-related operations. Or, you could have a search tag. Or a publish tag. Then, you can tell the AI the use case you want it to generate the README for, and it will find its way. Here’s a possible prompt that can do the work for you:
You are an API product writer creating a README for a public-facing API that does not yet have documentation.
Using the provided OpenAPI specification as the source of truth, write a section titled "Important Operations."
The use case you want to highlight as important is about <USE CASE>. Use OpenAPI tags to find all the relevant operations.
Explain how those operations work and how consumers can use them individually and also together to fulfill their needs. Show the technical information for each operation.
This is the OpenAPI document: https://example.com/openapi.yamlThis time, replace <USE CASE> with the name of the use case you want to focus on, and the OpenAPI URL with a real one. Then, run this prompt and see what it generates. Pretty good, right? You can even tell the AI to consider multiple use cases, or just a few of the operations. What’s important is that you have your OpenAPI document properly set up with all the right information, including the correct tags for each operation.
As I wrote above, I wouldn’t blindly rely on the generated results. If I were you, I’d review the generated README, make any necessary adjustments, and then publish it. The same process that generates the README for the first time can also update it every time your OpenAPI changes. However, I’d manually approve the changes every time, just to make sure everything has the highest possible quality. Yes, AI can generate an API README. However, as you now understand, you need to have your API properly documented in full. If you use a machine-readable format such as OpenAPI, that’s even better.