Swagger genera documentos de interfaz

En el desarrollo separado de front-end y back-end, el programador de back-end generalmente diseña la interfaz. Una vez finalizado, se debe escribir el documento de la interfaz y, finalmente, el documento se entrega al ingeniero de front-end, y el El ingeniero front-end se refiere al documento para el desarrollo.

Los documentos de interfaz se pueden generar rápidamente a través de algunas herramientas.Este proyecto utiliza Swagger para generar documentos de interfaz en línea.

¿Qué es Swagger?

La Especificación OpenAPI (OAS para abreviar) es un proyecto de la Fundación Linux, que intenta estandarizar el proceso de desarrollo de servicios RESTful mediante la definición de un lenguaje utilizado para describir el formato API o definición API. La versión actual es V3.0, y tiene ha sido lanzado y de código abierto en github.

（GitHub - OAI/OpenAPI-Especificación: El repositorio de especificaciones de OpenAPI）

Swagger es el marco de herramientas de desarrollo de API de OpenAPI Specification (OAS) más grande del mundo. Swagger es una herramienta de generación de documentos de interfaz en línea. Los desarrolladores front-end y back-end desarrollan basándose en documentos de interfaz. ( Documentación API y herramientas de diseño para equipos | Swagger )

Spring Boot puede integrar Swagger, y Swaager genera documentos de interfaz de acuerdo con las anotaciones en la clase Controller, que se pueden usar siempre que se agreguen las dependencias y la información de configuración de Swagger.

1. Agregue la dependencia swagger-spring-boot-starter al proyecto API

Java

<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
</dependency>

2. Configure la ruta del paquete de escaneo de Swagger y otra información en bootstrap.yml, el paquete base es la ruta del paquete de escaneo y escanee la clase Controller.

Java
swagger:
  título: "Sistema de gestión de contenido en línea Xuecheng"
  descripción: "El sistema de gestión del sistema de contenido gestiona la información relacionada con el curso"
  paquete base: com.xuecheng.content
  habilitado:
  versión verdadera: 1.0.0

3. Agregue la anotación @EnableSwagger2Doc a la clase de inicio

Inicie el servicio nuevamente, el proyecto se inicia, visite http://localhost:63040/content/swagger-ui.html para ver la información de la interfaz

La siguiente figura muestra la interfaz del documento de interfaz swagger:

Hay dos problemas con este documento:

1. El nombre de la interfaz muestra que el nombre de Course-Base-Info-Controller no es intuitivo

2. La consulta del curso es un método de publicación y solo muestra publicación/curso/lista.

Realice los cambios a continuación, agregue algunas anotaciones para la descripción de la interfaz y cambie RequestMapping a PostMapping, de la siguiente manera:

Bash
@Api(value = "Interfaz de edición de información del curso", tags = "Interfaz de edición de información del curso")
@RestController
public class CourseBaseInfoController { @ApiOperation("Interfaz de consulta del curso") @PostMapping("/curso/lista") public PageResult< CourseBase> list(PageParams pageParams, @RequestBody(required=false) QueryCourseParamsDto queryCourseParams){ //.... } }

5. Vuelva a iniciar el servicio, inicie el proyecto y visite http://localhost:63040/content/swagger-ui.html para ver la información de la interfaz

La siguiente figura muestra la interfaz del documento de interfaz swagger:

Habrá descripciones sobre los parámetros de la interfaz en el documento de la interfaz, y también se pueden agregar anotaciones a la clase del modelo para explicar los atributos en la clase del modelo, lo cual es conveniente para leer el documento de la interfaz.

Por ejemplo: el nombre del atributo marcado en rojo a continuación se puede marcar con un nombre chino a través de la anotación swager, lo cual es conveniente para leer el documento de la interfaz.

El método de etiquetado es muy simple:

Encuentre la clase del modelo y agregue anotaciones a las propiedades:

Java
public class PageParams { ... @ApiModelProperty("Número de página actual") private Long pageNo = 1L; @ApiModelProperty("Número predeterminado de registros por página") private Long pageSize = 30L; ... public class QueryCourseParamsDto { // Estado de auditoría @ApiModelProperty("Estado de auditoría") private String auditStatus; //Nombre del curso @ApiModelProperty("Nombre del curso") private String nombredelcurso; }

Reinicie el servicio e ingrese nuevamente el documento de la interfaz, como se muestra en la siguiente figura:

Las anotaciones comunes de Swaager son las siguientes:

Agregar anotaciones de Swagger a las clases de Java puede generar interfaces de Swagger. Las anotaciones de Swagger comunes son las siguientes:

Java
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiModelProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

@ApiImplicitParam属性如下：

属性	取值	作用
paramType		查询参数类型
	path	以地址的形式提交数据
	query	直接跟参数完成自动映射赋值
	body	以流的形式提交仅支持POST
	header	参数在request headers 里边提交
	form	以form表单的形式提交仅支持POST
dataType		参数的数据类型只作为标志说明，并没有实际验证
	Long
	String
name		接收参数名
value		接收参数的意义描述
required		参数是否必填
	true	必填
	false	非必填
defaultValue		默认值

使用Swagger可以进行接口的测试。

修改接口内容，添加一些测试代码

Java
@ApiOperation("课程查询接口")
@PostMapping("/course/list")
public PageResult<CourseBase> list(PageParams pageParams, @RequestBody(required=false) QueryCourseParamsDto queryCourseParams){

    CourseBase courseBase = new CourseBase();
    courseBase.setName("测试名称");
    courseBase.setCreateDate(LocalDateTime.now());
    List<CourseBase> courseBases = new ArrayList();
    courseBases.add(courseBase);
    PageResult pageResult = new PageResult<CourseBase>(courseBases,10,1,10);
    return pageResult;

}

debug方式启动，在 return 处打断点，再用swagger请求接口。

通过下图可以看到请求参数已经正常请求至controller方法

放行继续运行，观察swagger界面，结果可以正常返回

不过存在一个问题就是LocalDateTime类型的数据转json后数据格式并不是我们要的年月日时分秒。

Configure la clase LocalDateTimeConfig en el paquete com.xuecheng.base.config del proyecto base para realizar la conversión entre cadenas y tipos LocalDateTime al convertir a json

Swagger genera documentos de interfaz

Supongo que te gusta