Habilidades de escritura de documentos de interfaz fáciles de entender, eficientes y prácticas.

¡Hola a todos! Soy Sum Mo, un granjero de código de bajo nivel de primera línea. Por lo general, me gusta estudiar y pensar en algunos problemas relacionados con la técnica y organizarlos en artículos. Estoy limitado a mi nivel. Si hay expresiones inapropiadas en los artículos y códigos, no dude en aclararme.

El siguiente es el texto!

¿Qué es el documento de interfaz?

El documento de interfaz es una parte importante de un sistema de software, que describe todas las interfaces que pueden utilizar las aplicaciones externas en el sistema. En pocas palabras, el documento de interfaz es una guía que se utiliza para ayudar a los desarrolladores a desarrollar e interactuar con el sistema.

En el proceso de desarrollo de software, se requiere la interacción de datos y la transmisión de información entre diferentes sistemas, lo que requiere que el sistema proporcione algunas interfaces abiertas.

También existen muchas formas de presentación de documentos de interfaz, tales como: Swagger, Word, PDF, Postman, documentos de plataforma abierta, etc. Diferentes formas de presentación proporcionan diferentes soportes para presentar documentos de interfaz, pero la clave final es el contenido en sí mismo.

Un documento de interfaz claro, detallado y preciso es la clave para que el equipo de desarrollo pueda comprender y utilizar con precisión la interfaz del sistema.

En resumen, un buen documento de interfaz debe cubrir todos los escenarios de uso de la interfaz, ser detallado pero no extenso, y ser conveniente para que los desarrolladores lo encuentren y lo usen rápidamente. Para diferentes formas de visualización, los desarrolladores deben elegir el método de visualización más adecuado según las necesidades del proyecto y el proceso de desarrollo, a fin de mejorar la eficiencia del desarrollo y la calidad del trabajo.

Documentación de la interfaz Swagger

Swagger es un conjunto de herramientas para diseñar, construir, grabar y usar RESTful API. Puede generar automáticamente documentación de API y proporcionar una interfaz de usuario interactiva, lo que puede mejorar en gran medida la eficiencia del desarrollo y la eficiencia de la colaboración. Admite múltiples marcos y lenguajes de programación, y puede generar múltiples formas de presentación, como herramientas como Swagger UI, Swagger Editor y Swagger Codegen. Al mismo tiempo, Swagger también proporciona potentes funciones de administración de API, que incluyen monitoreo, depuración, prueba y seguridad de API, etc., que pueden ayudar a los desarrolladores a administrar y mantener mejor las API.

enséñalo

método de acceso uno

DIRECCIÓN:http://localhost:8080/swagger-ui.html#/

página delantera

Página de detalles

Método de acceso dos

DIRECCIÓN:http://localhost:8080/doc.html

página delantera

barra lateral

Página de detalles

SpringBoot integra Swagger2

1. Archivo de configuración

Proyecto SpringBoot pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.6.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>springboot-swagger</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>springboot-swagger</name>
    <description>Demo project for Spring Boot</description>
    <properties>
        <java.version>1.8</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.2</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

Aquí debe prestar atención a un problema de versión correspondiente.Si usa una versión superior del marco SpringBoot y una versión inferior de Swagger,
aparecerá el siguiente error:

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
	at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:181)
	at org.springframework.context.support.DefaultLifecycleProcessor.access$200(DefaultLifecycleProcessor.java:54)
	at org.springframework.context.support.DefaultLifecycleProcessor$LifecycleGroup.start(DefaultLifecycleProcessor.java:356)
	at java.lang.Iterable.forEach(Iterable.java:75)
	at org.springframework.context.support.DefaultLifecycleProcessor.startBeans(DefaultLifecycleProcessor.java:155)
	at org.springframework.context.support.DefaultLifecycleProcessor.onRefresh(DefaultLifecycleProcessor.java:123)
	at org.springframework.context.support.AbstractApplicationContext.finishRefresh(AbstractApplicationContext.java:935)
	at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:586)
	at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.refresh(ServletWebServerApplicationContext.java:145)
	at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:740)
	at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:415)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:303)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1312)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1301)

Esto es porque:因为Springfox 使用的路径匹配是基于AntPathMatcher的，而Spring Boot 2.6.X使用的是PathPatternMatcher。

Las siguientes versiones son compatibles

Versión SpringBoot	versión arrogante
2.5.6	2.9.2

Versión SpringBoot	versión arrogante
2.6.5	3.0.0

2. Código del proyecto

estructura del proyecto

SwaggerConfig.java

package com.example.springbootswagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {
    
    

    @Bean
    public Docket createDocket() {
    
    
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(true)
                .groupName("我的接口文档")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.springbootswagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
    
    
        return new ApiInfoBuilder()
                //标题
                .title("凤求凰")
                //作者、链接、邮箱等
                .contact(new Contact(
                        "司马相如",
                        "https://hanyu.baidu.com/shici/detail?pid=ecb82707a98c418995c5a0c50b770af0&from=kg0",
                        ""
                ))
                //描述
                .description("有一美人兮，见之不忘。\n" +
                        "一日不见兮，思之如狂。\n" +
                        "凤飞翱翔兮，四海求凰。\n" +
                        "无奈佳人兮，不在东墙。\n" +
                        "将琴代语兮，聊写衷肠。\n" +
                        "何日见许兮，慰我彷徨。\n" +
                        "愿言配德兮，携手相将。\n" +
                        "不得於飞兮，使我沦亡。\n" +
                        "凤兮凤兮归故乡，遨游四海求其凰。\n" +
                        "时未遇兮无所将，何悟今兮升斯堂！\n" +
                        "有艳淑女在闺房，室迩人遐毒我肠。\n" +
                        "何缘交颈为鸳鸯，胡颉颃兮共翱翔！\n" +
                        "凰兮凰兮从我栖，得托孳尾永为妃。\n" +
                        "交情通意心和谐，中夜相从知者谁？\n" +
                        "双翼俱起翻高飞，无感我思使余悲。")
                //更新说明
                .termsOfServiceUrl("这是第一版")
                //版本号
                .version("1.0.0").build();
    }
}

TestController.java

package com.example.springbootswagger.controller;

import com.example.springbootswagger.req.AddReq;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

@RestController
@Api(tags = {
    
    "测试接口类"}, hidden = true)
@RequestMapping("/test")
public class TestController {
    
    

    @ApiOperation("GET请求，查询方法")
    @GetMapping("/query")
    public String query() {
    
    
        return "查询成功";
    }

    @ApiImplicitParams({
    
    
            @ApiImplicitParam(name = "param1", value = "参数1", required = true),
            @ApiImplicitParam(name = "param2", value = "参数2", required = false)
    })
    @ApiOperation("PUT请求，添加方法")
    @PutMapping("/update")
    public String update(
            @RequestParam(required = true) String param1,
            @RequestParam(required = false) String param2) {
    
    
        return "更新成功";
    }

    @ApiOperation("POST请求，修改方法")
    @PostMapping("/add")
    public String add(@RequestBody AddReq addReq) {
    
    
        return "添加成功";
    }

    @ApiImplicitParam(name = "id", value = "用户ID", required = true)
    @ApiOperation("DELETE请求，删除方法")
    @DeleteMapping("/del")
    public String del(Long id) {
    
    
        return "删除成功";
    }
}

AddReq.java

package com.example.springbootswagger.req;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("添加参数")
public class AddReq {
    
    

    @ApiModelProperty("名字")
    private String name;

    @ApiModelProperty("密码")
    private String password;

    public String getName() {
    
    
        return name;
    }

    public void setName(String name) {
    
    
        this.name = name;
    }

    public String getPassword() {
    
    
        return password;
    }

    public void setPassword(String password) {
    
    
        this.password = password;
    }
}

SpringbootSwaggerApplication.java

package com.example.springbootswagger;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
@SpringBootApplication
public class SpringbootSwaggerApplication {
    
    

    public static void main(String[] args) {
    
    
        SpringApplication.run(SpringbootSwaggerApplication.class, args);
    }

}

Word, PDF y otros documentos de interfaz de tipo de archivo

¿Por qué necesita un documento de interfaz similar a un archivo? En primer lugar, el documento de Swagger tiene problemas de compatibilidad y algunos sistemas no lo admiten.En este momento, el documento de interfaz de archivos puede resultar útil. En segundo lugar, el documento Swagger no se puede utilizar sin conexión. Si la red es inestable o no hay conexión de red, el documento de la interfaz no se puede ver, mientras que el documento de la interfaz del archivo se puede examinar sin conexión en cualquier momento.

He escrito un artículo sobre la interacción entre sistemas antes: cuando cooperan varias partes, ¿cómo se realiza la interacción entre sistemas? , La interacción de la interfaz entre los sistemas generalmente proporciona documentos de tipo archivo, como Word y PDF.

En el desarrollo real, descubrí que existen grandes diferencias en el formato de los documentos de interfaz proporcionados por diferentes equipos de desarrollo. Algunos equipos brindan documentación muy detallada e incluso brindan códigos de muestra para llamar, mientras que otros equipos solo brindan descripciones de interfaz muy simples, ni siquiera descripciones de parámetros. En este caso, si la documentación de la interfaz es muy detallada, puedo depurar y depurar rápidamente, pero si la documentación no es lo suficientemente detallada, es fácil encontrar varias trampas (pocos que son difíciles de describir en una palabra), y tiene que encontrar el desarrollo de la otra parte.

Creo que un buen documento de interfaz debe incluir lo siguiente:

• Descripción general de la interfaz: incluye información como el nombre, la descripción y el número de versión de la interfaz, lo que permite a los desarrolladores comprender la información básica de la interfaz.

• Parámetros de la interfaz: incluidos los parámetros de solicitud y los parámetros de retorno. Es necesario especificar el nombre, el tipo, la descripción, el valor predeterminado y si se requiere para cada parámetro en detalle, para que los desarrolladores puedan saber claramente el significado y el uso de cada parámetro.

• Ejemplos de uso de la interfaz: proporcione una o más solicitudes y los ejemplos correspondientes, para que los desarrolladores puedan comprender mejor cómo usar la interfaz y obtener resultados.

• Códigos de error de la interfaz: enumere todos los códigos de error posibles y los mensajes de error correspondientes, lo que permite a los desarrolladores comprender cómo identificar y manejar los errores devueltos por la interfaz.

• Restricciones y seguridad de la interfaz: incluyendo restricciones de acceso, restricciones de frecuencia, seguridad y otra información de la interfaz, para que los desarrolladores sepan cómo usar la interfaz correctamente.

El siguiente es un ejemplo de un documento de interfaz de plantilla de Word que creo que tiene un estilo más conciso y claro (la parte inferior es el enlace de descarga de la plantilla):

Enlace de descarga de plantilla