How to write API documentation with free?

What is the best tool for API documentation?

JSDoc.

Io

I saw a lot of discussion on twitter lately about the correct tool to use for API documentation and that's why I have a feeling some people might want me to write about it here :) So what is best documentation tool? To start let's remember what does documentation look like before the advent of JSDoc and similar tools. Back in 2024 or 2024 there was no easy solution for simple documentation. The most commonly used method was to create a wiki, that allowed you to store simple documentation quickly and easily. But when there are only 10 pages of comments it does not give any chance to really elaborate documentation. You can get some information from Wikipedia, it works ok but it's not always the most convenient to find out about a library. Also wikis tend to create a really low-quality documentation, due to the quick implementation.

The best solution until now was definitely books. In particular books for JS programmers and also books for JavaScript frameworks. They have the highest quality level and they store enough detail about the library/framework/module. They are also slow to create, it takes time to do the research, the copy&paste of the text and then they require a good quality of writing. What if I could create a book automatically without any mistakes or any time spent on the research?

It's 2024 and we live in a fast world, where things change quickly and it's necessary to react to the changes quickly. If you search Google Trends for javascript modules you'll see there is a huge demand for a quick and easy to create documentation for your project. This trend is not going to slow down in the foreseeable future and so we need some new solutions.

Why does this exist? You need documentation and it takes time to create it, that doesn't go well with JS development, which should be a real-time process! So if you need a documentation of a library/framework/module in a short time you would certainly choose to create the documentation using one of the existing tools. You just created your documentation and you want it to be available to anybody in the project? Then there are two ways to go: Deploy it to GitHub and simply link it from your README .gitlab-ci.

Is Swagger API documentation free?

Is it open?

We all love Swagger. So many open source projects are based on Swagger, it's used by thousands of services, so it's pretty common.

Unfortunately the Swagger web service is a proprietary closed source product and they have no plans to open source it. It's written in Java and licensed under Apache 2.0 but that doesn't mean much (Java is open source as well).

Open API specifications like REST or JSON Schema provide a more portable alternative. But these are only free for the community, not for you. Some companies like Twitter and Etsy seem to like licensing agreements but not much more.

So let's be free. Let's open source all swagger.js API docs. The JavaScript is small enough it won't impact your server side logic or API. But the docs could help you figure out how to use your own services without their API documentation.

The team wants me to open source it. I don't. Let me quote myself:

As a matter of principle, I'll do my utmost to keep Swagger API documentation closed source. In practice, I'm not in the business of making decisions that will limit my company's growth, or even my ability to find new developers for our service.

I want my company's products to be sustainable. If we build products that require Swagger in order to be useful, we have no business if Swagger becomes a proprietary product owned by someone else. Or if we get hit by a lawsuit.

It doesn't really make sense for a technology to depend on a product's ability to be licensed so we can support it in perpetuity. That's what the Apache 2.0 license is for; to encourage developers to share code for the long run. If everyone would just make Swagger docs and use it freely then we'd have a sustainable open source product that companies would be willing to use.

So while I can't promise you an open source swagger anytime soon, I'll start working on it now to get something available before the end of this year. Here's some details: How does it work? The documentation website is written in plain HTML and served up using apache2 . A swagger server runs on port 9200, which accepts requests for /api/swagger-ui.html.

What is a good API documentation layout?

A good documentation layout is the most important and overlooked part of any API.

I believe the layout will help a developer to write better code as they need to read documentation while coding.

My goal is to design the best documentation for our users and to make it as easy as possible to use. In this article, I am sharing three layouts for all types of APIs: JSON, REST and GraphQL. You will learn how to layout your API documentation in a format that encourages people to read more about it and find the things they are looking for easily. These layouts are in the style of Wikipedia. I call it the Infinitely Scrollable layout.

If you are looking for a single image that will automatically create a documentation layout for you, there is one for every format. You can find them in this GitHub repository.

Format: How to read your documentation. The first thing you need to do is to think of what kind of information your API provides to the user. A lot of times developers try to make the documentation look like a Wikipedia article and they end up with a hard-to-read mess.

As a developer, the way to figure out how to write good documentation is to think about how you would want to use your API. You must know how you will use it. For example, if you want to build a mobile app, you need to know the mobile-optimized features of the API. In case you want to build an e-commerce website, you should know how to use the product API. And so on.

In my opinion, this is the most important step to writing good documentation. Let's assume we have an API called /exampleapi with a set of resources (documentation). This documentation is not only for a human. We need to write code that makes sense for our program and this includes a documentation-driven developer.

How we can understand the documentation? For me, the first thing that I want to know is: What is the name of the resource, ie, the /exampleapi/documentation endpoint. What are the key properties of the resource (what is its purpose, status, description). What are the default values for the resource. How can I consume or use this resource. What are the parameters, if any. How can I retrieve this resource.

How to write API documentation with free?

I have been asked to write API documentation for the company's APIs and I am looking for free tools to help me out.

I have done it before, but was not really happy with the tool I used.

I do a lot of writing, especially in my day job. I currently use Writeboard, which is fine, but I'm looking for something a little better.

There are quite a few paid options available, but nothing that is particularly appealing to me (maybe not even available). So, I was thinking about taking a look at the open source version of what they have now. That's where I'm at right now.

I want to know what people think of this idea. In particular, can anyone recommend a tool that would be appropriate for this use case? Update: I looked at Joomla! and their documentation tool. It's decent, but it doesn't support Markdown as a WYSIWYG editor. It's just plain text. Also, it seems to need to be installed separately on each server. So, it might work for me, but that's not exactly ideal.

I have been looking at MarkdownEdit. I really like the setup that they have. In particular, I like that it's not just plain text, but that it actually supports formatting. That's something I've wanted for a long time.

One problem that I had with Writeboard, is that there is no way to turn off the Markdown formatting when you copy/paste into the editor. That meant that formatting was not preserved. In MarkdownEdit, the same problem doesn't exist.

You will have to use the built-in editor, but you can easily disable the "bold" and "italic" buttons by clicking on them to remove the highlight. The other issue I have with the MarkdownEdit is that it needs to be installed on each server you want to use it on. That's a real drag for me. I want to be able to just access it from a web browser, and not have to install anything.

As I mentioned in another post, I also looked at Joomla's documentation tool. I'm not a big fan of the Joomla! brand of CMS, so I didn't really spend much time looking at it.

I am familiar with how it works. That's the problem.