Documentación interactiva

What is interactive API documentation?

Interactive documentation is a fundamental part of a well-structured API. With it, we can see and test different aspects of our API in a visual and practical way. To better understand how it works, we will explore some key points, such as the use of Swagger UI and how information is presented in JSON and JSON-LD formats.

How does Swagger UI work?

Swagger UI is a tool that allows us to visualize and test the responses of an API that follows the OpenAPI 3.0.0 standard. This standard helps us to structure the information in a way that can be easily understood. With Swagger UI, you can:

• Test routes and methods: allow you to test API functionality without the need for external tools.
• Explore data: You can view details such as categories and publications provided by the API.
• View API responses: When testing a function, such as updating an element, you can view the immediate API response.

For example, to view the items in a category, you simply click the button to execute and the results are displayed directly in the documentation.

What are JSON and JSON-LD?

When working with data in APIs, JSON and JSON-LD formats are crucial.

• JSON (JavaScript Object Notation): This is the standard format for data exchange. It uses key-value pairs, where the key is a string and the value can be a number, string, Boolean, etc.

• JSON-LD (JavaScript Object Notation for Linked Data): It is an extension of JSON that allows representing linked data. Used to provide additional semantics to data with special elements starting with the @ symbol.

For example, JSON-LD can show how a category within a database has a unique entity with a unique ID, which is useful for creating more machine-understandable data structures.

Why mark entities as API resources?

When developing APIs with API Platform, an important practice is to mark entities as API resources. This is accomplished through annotations within the classes that make up our application:

• Operation Configuration: This allows us to define how data should respond to different HTTP operations such as GET, POST, PUT, PATCH and DELETE.

• Ease of customization: Through these annotations, we can customize how our entities behave in the context of the API.

In other words, by marking an entity, you are giving the possibility to easily manipulate its operations, which improves control and flexibility when working with data in the API.

How are API routes managed?

Route management is essential for the proper functioning of an API. You can perform specific operations to manage routes:

• Command to display routes: Using php bin/console debug:router helps to review all routes that the API has, including category and post routes.

• Routes customization: It is possible to change the prefix of API endpoints to adapt them to different versions or specific needs. For example, you can change "API" to "APIMIA" or specify the use of "API version 1".

These techniques make the paths understandable and reflect the intentions of the developer or company behind the API, making it easier to maintain and evolve.

Why is it important to experiment with interactive documentation?

Experimenting with the interactive documentation, trying different operations and configurations, is fundamental to deeply understand how the API works and how to manipulate the data it handles. Performing practices and manipulations in the interactive environment will not only give you confidence and skills, but will also allow you to quickly adapt to future changes or integrations with new services.

It is essential to invest time in exploring, learning and mastering interactive documentation tools to maximize the potential of any project within API development.