Inicio rápido de Swagger (springBoot integra Swagger)

1. Antecedentes

En el desarrollo de separación de front-end y back-end, el programador de back-end generalmente diseña la interfaz, una vez completado, se debe escribir el documento de la interfaz y finalmente entregar el documento al ingeniero de front-end, quien se refiere al documento para el desarrollo.

Los documentos de interfaz se pueden generar rápidamente a través de algunas herramientas.

2. ¿Qué es la arrogancia?

OpenAPI Especificación (OAS para abreviar) es un proyecto de la Fundación Linux. Intenta estandarizar el proceso de desarrollo de servicios RESTful definiendo un lenguaje utilizado para describir formatos API o definiciones API. La versión actual es V3.0, y ha sido lanzada y Código abierto en github. (Enlace: GitHub - OAI/OpenAPI-Specification: The OpenAPI Specific Repository )
Swagger es el marco de herramientas de desarrollo de API de especificación OpenAPI (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 en base en el documento de interfaz. (Sitio web oficial: https://swagger.io/ )
Spring Boot puede integrar Swagger, y Swaager se basa en las anotaciones de la clase Controller.Generar documentación de interfaz, simplemente agregue las dependencias y la información de configuración de Swagger para usarlo.

3. El papel de Swagger

Generación automática en línea de documentación Rest API.
prueba de funcionamiento.

4. Arrogancia integrada Spring Boot

Preparar:

(Nota: También puedes usar otras versiones. Si no es compatible, considera la siguiente versión)

JDK1.8
SpringBoot2.3.4 + maven3.8.1

1. En el proyecto SpringBoot, importe las dependencias de swagger

        <!-- Spring Boot 集成 swagger -->
        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>1.9.0.RELEASE</version>
        </dependency>
         <!-- swagger注解的jar包 -->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
             <version>1.5.20</version>
        </dependency>

2. Agregue la anotación @EnableSwagger2Doc a la clase de inicio correspondiente para iniciar Swagger.

Insertar descripción de la imagen aquí

3. Configuración del archivo de configuración Swagger (por ejemplo: application.yml, bootstrap.yml, etc.)

(Nota: debido a que Swagger usa archivos de configuración yml, no es necesario escribir la clase de configuración SwaggerConfig)

Insertar descripción de la imagen aquí

La configuración es la siguiente (esto es sólo una parte):

swagger:
  title: "这里是一个title"
  description: "这里是一个description"
  base-package: com.xuecheng.content  #必需，接口包扫描路径
  enabled: true
  version: 1.0.0

Después de iniciar el servicio correspondiente, el navegador accede a
http://localhost: número de puerto del servicio correspondiente/swagger-ui.html

Insertar descripción de la imagen aquí

4. Anotaciones comunes para la arrogancia

@Api : se utiliza en la clase Controlador para describir la función de esta clase.

Ejemplo:

@Api(value = "课程信息编辑接口",tags = "课程信息编辑接口")
@RestController //相当于@Controller与@ResponseBody(响应json数据)
public class CourseBaseInfoController {
    
    

    @Autowired
    CourseBaseInfoService courseBaseInfoService;


    // @RequestBody(required = false)表示可以为空，它默认为true，不允许为空
    @ApiOperation("课程查询接口")
    @PostMapping("/course/list")
    public PageResult<CourseBase> list(@ApiParam("分页参数") PageParams pageParams, @RequestBody(required = false) QueryCourseParamsDto queryCourseParamsDto){
    
    

        PageResult<CourseBase> courseBasePageResult = courseBaseInfoService.queryCourseBaseList(pageParams, queryCourseParamsDto);
        return  courseBasePageResult;
    }
}

@ApiOperation : se utiliza en métodos para describir la función del método.
@ApiParam : utilizado en parámetros para describir la función del método

como:

    @ApiOperation("课程查询接口")
    @PostMapping("/course/list")
    public PageResult<CourseBase> list(@ApiParam("分页参数") PageParams pageParams, @RequestBody(required = false) QueryCourseParamsDto queryCourseParamsDto){
    
    

        PageResult<CourseBase> courseBasePageResult = courseBaseInfoService.queryCourseBaseList(pageParams, queryCourseParamsDto);
        return  courseBasePageResult;
    }

@ApiModel : utilizado en clases de modelo para anotar clases de modelo
@ApiModelProperty : utilizado en variables miembro (propiedades) para anotar variables miembro

Ejemplo:

@Data
@ApiModel(value="TeachplanDto", description="课程计划信息Dto")
public class TeachplanDto extends Teachplan {
    
    


    @ApiModelProperty(value = "与媒资管理的信息")
    private TeachplanMedia teachplanMedia;

    @ApiModelProperty(value = "小章节list")
    private List<TeachplanDto> teachPlanTreeNodes;
}