How to create API documentation ?

Basic information about api documentation, how to create one, how to make it useful ?

What is document ?

Document that describes handling, functionality and architecture of a technical product or a product under development or use. The intended recipient for product technical documentation is both the end user as well as the administrator / service or technician.

Why do we need document?

• The presence of documentation helps keep track of all aspects of an application and it improves on the quality of a software product. Its main focuses are development, maintenance and knowledge transfer to other developers.
• Documentation help ensure consent and expectations.
• Any professional is always looking for ways to improve, or a better approach, a more successful course of treatment, or fresh ideas to tackle ongoing problems. Documentation is crucial in achieving these measures. 

Who should write document? Or How to write Document ?

• focus on the reference materials,
• make sure that the organization is clear and that the content is cross referenced, and
• make sure that you focus on being as clear and forthright as possible.
• Use structured conventions to make reading easier.
• Use short clear sentences.
• Reduce redundancy.
• Always provide context and explain examples.
• Cross reference extensively.

What is API ? Why do we need API ? 

• An application program interface (API) is a set of routines, protocols, and tools for building software applications. Basically, an API specifies how software components should interact. Additionally, APIs are used when programming graphical user interface (GUI) components.

• APIs are also used to control access to hardware devices and software functions that an application may not necessarily have permission to use. That’s why APIs often play a big role in security.

What is API Documentation?

• API documentation is a technical content deliverable, containing instructions about how to effectively use and integrate with an API. It’s a concise reference manual containing all the information required to work with the API, with details about the functions, classes, return types, arguments and more, supported by tutorials aand examples.
• The third-party developer, who is your API’s main consumer, is busy solving complex programming challenges. Your API is a means to an end for the technical user, and they want to integrate as quickly as possible to move forward in their software development, meaning they should immediately understand the value and usage of your API. The aggregate experience of the developer when discovering, learning to use, and finally integrating with an API is termed as Developer Experience (DX).
• API documentation is the key to a great DX.

Why do we need api documentation?

• Transform Requirement documentation in to methods by using technical documentation which could be known as High level design document or Low level design document
• Technical lead can create HLD or LLD and give it to developer.
• 0 years – 2 years experience can write methods and its body or implement concrete methods of interface designed by Tech lead (more experienced )
• Among all the phases of the API lifecycle, documentation is probably the area showing the most growth.
• This is especially true with the tooling ecosystem around documentation. It’s interesting to note this trend since documentation is traditionally something that developers paid little attention to when launching code. In fact, it’s much easier to implement code, than is it to write good documentation.
• But this is because of its direct impact on adoption and usage. You can have the best, most functional product, but no one will use it if they don’t know how to. Documentation is the foundation for good Developer Experience.
• Improved User Adoption
• Increased Awareness
• Saves Support Time and Costs
• Easier Maintenance

How to document APIs of your application ?

Design First: 

The Design First approach advocates for writing your API definition before writing any code.

An effective API design helps you and all members involved quickly understand your API’s resources and value propositions, reducing the time taken for them to integrate with your API.

Identifying design issues before writing any code is more efficient than catching issues after the implementation is done.

Code First

The Code First approach advocates for writing implementation code first before designing and writing your API definition.

This approach ensures that your definition is consistent with your implementation. But you need to make sure the definition has human-friendly descriptions and examples.

If you follow this approach, there are tools and packages that allow you to generate documentation from existing APIs:

What is OPEN API Specification?

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

What is swagger ?

Swagger allows you to describe the structure of your APIs so that machines can read them. The ability of APIs to describe their own structure is the root of all awesomeness in Swagger. Why is it so great? Well, by reading your API’s structure, we can automatically build beautiful and interactive API documentation. We can also automatically generate client libraries for your API in many languages and explore other possibilities like automated testing.