¿Cómo escribir documentación de la interfaz API?
En el proceso diario de desarrollo de proyectos, la documentación de la interfaz es esencial. Se necesitan documentos de interfaz entre los ingenieros de back-end y los ingenieros de front-end para definir los protocolos de transmisión de datos, se necesitan documentos para describir las interfaces expuestas externamente del sistema, se necesitan documentos para registrar los protocolos de interfaz cuando se llaman entre sí entre sistemas, etc. Para un proyecto completo, la documentación de la interfaz es crucial. Entonces, ¿cómo escribimos un documento de interfaz? Hoy hablemos de varios elementos importantes de los documentos de interfaz.
1. Descripción general de la interfaz
La descripción general de la interfaz describe principalmente los puntos de función comercial involucrados en este documento de interfaz, los objetos de lectura a los que está orientado y qué interfaces comerciales incluye principalmente el documento de interfaz. , para que los lectores puedan tener una comprensión intuitiva. Por ejemplo: este documento define la interfaz de protocolo de datos del sistema de extremo medio para partes de acceso externo, que incluye principalmente: interfaz de registro de usuario, sincronización de usuario, autenticación de autorización y otras interfaces. Es adecuado para que lo lean desarrolladores de nivel medio o socios externos. Esta descripción puede brindar a los lectores una comprensión general de todo el documento de la interfaz.
2. Descripción del permiso
Algunas llamadas a la interfaz requieren autenticación de autorización, que debe explicarse en esta parte. Si la interfaz se basa únicamente en la autenticación del token asignado, el documento debe explicar cómo obtener el token. Si la interfaz requiere autenticación de firma, el método específico de firma debe explicarse aquí:
Las reglas de generación del parámetro de firma deben explicarse en detalle, preferiblemente con un ejemplo, como por ejemplo:
Así es como se hace. La parte entrante puede verificar si su método de firma es correcto.
3. Método de codificación
Durante el proceso de solicitud de la interfaz, la codificación puede causar caracteres confusos. Por lo tanto, la interfaz debe aceptar el método de codificación. método de escritura:
4. Descripción de la solicitud
La descripción de la solicitud del documento de interfaz describe principalmente el nombre de dominio solicitado por la interfaz y el formato de datos solicitado: como
5. Lista de interfaces
La lista de interfaces es la interfaz. El contenido principal del documento debe enumerar todos los nombres de las interfaces, las direcciones de las interfaces, los métodos de solicitud de las interfaces, los parámetros de las solicitudes de las interfaces y los formatos de respuesta. En los parámetros de solicitud de la interfaz, debemos explicar el significado, el tipo y si se requieren atributos de cada parámetro. Para el resultado de la respuesta de la interfaz, si hay campos comerciales, también es necesario explicarlos. El siguiente es un ejemplo relativamente completo:
6. Descripción del código de estado
El cuerpo de respuesta de la interfaz generalmente contiene el código de estado de respuesta, como éxito, error, etc. El código de estado ayuda a la parte de acceso a determinar el estado de la llamada de interfaz. Por ejemplo:
Si el documento de interfaz puede reflejar los elementos anteriores, puede considerarse como un documento de interfaz completo, que la parte que accede puede leerlo y comprenderlo bien.