An API service and its documentation
Suppose we have a Zato service with I/O as defined below ..
# -*- coding: utf-8 -*- # Zato from zato.server.service import Service class Login(Service): """ Logs a user in. - Sets session to expire in 24 hours if unused - Metadata stored for each session: - Creation time in UTC - Remote IP and fully-qualified name """ name = 'my.api.login' class SimpleIO: """ * user_name - User name to log in as * password - User password * token - Session token * user_id - User's ID * user_display_name - User's display name, e.g. first and last name * user_email - User's email * preferred_language - User's preferred language in the system """ input_required = 'user_name', 'password' output_required = 'token', 'user_id', 'user_display_name', 'user_email' output_optional = 'preferred_language' def handle(self): # Skip actual implementation pass
.. here is how its documentation will look like with the dark theme as generated by zato apispec.
Note that, as previously, the quick access WSDL and OpenAPI links are in the downloads section, to the left hand side.
Coming up next
Yet, there is more. The new theme is but a part of a series of works focused on API documentation and specifications. Coming up next are:
- A service invoker to execute services directly from their documentation
- A mobile version
- Searchable API specications
Stay tuned for more news.