preface

This article focuses on a new development approach: reading the code directly from the API documentation by reversing the development sequence. The authors argue that by developing this way, you can have a clearer idea of what the document says and how it should be implemented.

If you start from the API documentation alone, it is often difficult to understand the specific functions it wants to achieve due to the lack of information. Because of this assumption, you often think of improving the documentation after development. But this habit for any developer, is not a good thing, they will be assigned in a project to complete various tasks, whatever the task, must be accurate understanding each function, we can find the suitable way to finish the work, and the role of a perfect document which is able to make you a better understanding of specific tasks.

Faced with the approaching deadline for project acceptance, we had to focus all our energy on development, leaving little time to process and improve project documents, which were generally only written in outline. Therefore, when you find very sketchy information in the documentation, you can only hope to recall the development details at the time, otherwise you will not be able to speak at the time of acceptance.

If there are requirements for completeness and correctness in the acceptance criteria, and users can rate this, the completeness of the document will be greatly improved.

Documentation can be a valuable resource to the development team if the required details are already documented before you write a lot of code. Because this document can be shared between the development team and testers, all can use such an API at the same time. On the other hand, the interactivity of the team highlights the importance of documentation in API development.

When you want to find a document, you can interactively call the document directly from the project, which will make it easier for developers to call the API when completing tasks, effectively reducing the time developers spend debugging the interface.

Now that we know how important API documentation is, let’s look at how documentation design should be designed.

3 important features in API documentation design

These are the three features THAT I think should be present in documentation:

  • 1. Keep things synchronized, which means that if something is added during development, it should be immediately known from the documentation, and even if it is behind schedule, keep the documentation up to date with the development schedule as soon as it is released.

  • 2. The content of the document should provide the complete content of the whole function of the project, and the implementation method should also be recorded in the document for the developer to look back and make up for the defects.

  • 3. Documentation should serve as a guide and specification to help developers with different roles achieve the same business goals, also be used to test apis, and help improve communication between development teams. If you can, offer rewards for improving documentation.

Basic API documentation section

How do you verify the identity of the API user? First you need an authentication scheme.

  • 1. If you are using OAuth, don’t forget to explain how to set up OAuth and get the API key in the documentation.

  • 2. You need to document any errors you encounter during development and the problems they cause, and you should explain in your documentation whether the error violates the error standard, known as a failure example.

  • 3. You need records that contain endpoints and information about how to use them, including request information and return information. This is the most important part of the API documentation.

Keep track of these three sections, and you’ll be off to a good start, because you already have most of what you need to use the API. It’s also much easier for testers to test apis against your documentation.

This is often not enough, however, and as you encounter more complex situations, you need to provide additional documentation of the non-functional aspects of the API to supplement it.

What else should the API document contain

  • 1. Explain the function of each parameter in the API documentation.

  • 2. Examples of API calls for various languages and tools (cURL, Postman, etc.). These examples are likely to be used many times and are arguably the most important part of the API documentation.

  • 3. Specify the workflow when calling the API.

  • 4. Overview of design principles adopted by API providers, such as REST (especially hypermedia), HTTP code, etc.

  • 5. Information about authentication, including other possible implementations, such as OAuth or OpenID Connect.

  • 6. General information about error handling and information about HTTP return codes.

  • 7. An interactive API explorer that allows developers to easily bring all this information to life.

Start writing your API documentation

Start by documenting the requirements for each feature, and your documentation should be shareable. Only then can the viewer gain information about how to properly develop the project, especially internal developers who need to understand the document to explain the project.

After you document an API project, it’s a good idea to translate the written comments and other content of the document into colorful web sites and other customizable templates, if possible, that will help generate a complete site for the project.

Three API document template standards

Of all the API document formats, three are worth mentioning because they allow you to design the API either manually or automatically:

  • 1.Swagger and Open API. You can easily generate your own API server code, client code, and documentation itself. The Open API Initiative (OAI) focuses on creating, developing and promoting vendor-neutral API description formats based on the Swagger specification.

  • 2. RAML. The RESTful API modeling language system provides an easy way to specify API usage patterns.

  • 3. The API Blueprint. This is a standard based on the Markdown format that allows you to easily generate code from documents.

In addition to the three API standards mentioned by the author, EOLINKER supports automatic reading of code annotations to generate API documents, which greatly improves the efficiency of developer documentation. If you are interested in EOLINKER API Studio, you will not mention a product interface image www.eolinker.com

conclusion

As a developer, you need to understand the importance of documentation if you want to ensure that your API is well understood by others. While some people acknowledge the above and think it’s a good idea to start a project with API documentation, the reality is that most people are still trying to write things that don’t involve documentation.

If you plan your document from the beginning, once you’re done, you’ll have more time to work on the main project. Having good documentation can save you a lot of time in the long run and can help you build projects more easily.

Originally written by Guy Levin

Translation and modification: EOER

Original address: dzone.com/articles/do…