软件工程应用与实践——swagger2搭建

Posted 2022-12-14 叶卡捷琳堡

2021SC@SDUSC

文章目录

• • 一、概述
  • 二、搭建swagger2
  • 三、总结

一、概述

在本项目中，我的主要工作是负责前端和后端，以及前后端交互代码的阅读和理解，在之前的博客中，主要介绍了前端和后端的一些技术，但对于前后端交互的内容介绍得比较少，因此经过小组讨论，我决定在本篇博客重点研究swagger2的搭建。

现在的软件开发大多采用前后端分离的方式，而前后端分离的一个痛点在于后端API接口的管理和测试，早期后端API接口采用人工管理的方式，但对后端API接口的统计和测试较为繁琐。而后端接口经常需要根据需求进行实时变化，因此一款高效的，管理前后端接口的工具就应运而生了。swagger2在企业开发中主要用于Restful API的自动生成，调试等工作，免除了接口人工管理，单独测试的缺点。

二、搭建swagger2

由于本项目后端使用Spring Boot，而swagger2可以快速整合到Spring Boot项目中。在本项目中，成功利用Spring boot整合swagger2。

引入依赖

搭建Swagger2需要添加相关的依赖，添加了两个依赖，一个是Swagger2驱动的依赖，另一个是Swagger2API接口文档的界面的依赖（即swagger-ui）

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.2</version>
</dependency>

添加Swagger2配置类

• 利用@Configuration注解表明这是一个配置类，并注入Spring容器中，该对象由Spring容器管理，不需要程序员管理该对象的创建和释放
• 通过@EnableSwagger2注解开启Swagger2，表明这个类配置了Swagger2，在这个类中主要配置的是一个Docket，Docket中的配置内容主要是关于接口文档中的基本信息
• 通过apis方法配置要扫描的controller位置，通过paths方法配置路径
• 在apiInfo中配置接口文档的基本信息。如描述信息，版本号等

package com.huang.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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig

    @Bean
    Docket docket()
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sdu.com.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .description("老年健康系统接口文档")
                        .version("v1.0").title("API接口文档").build());
    

利用Swagger2开发接口

在本项目中，所有的controller均配置类Swagger2对应的注解，下面对配置代码进行分析

• 用@Api注解的作用域在类上，使用tags属性用来描述整个controller的基本信息
• 使用@ApiOperation注解用来描述一个方法的基本信息，使用values属性对方法作用进行简短描述，notes属性用来表明方法的详细作用
• 使用@APiImplicitParam注解表明方法的参数，并描述参数的含义，path表明使用路径的方式接收参数，name表明参数名称，value用户描述参数，required用于表示参数是否必填
• @ApiResponse注解是对相应结果的描述，code表示响应码，而message用于体现该响应码对应的描述信息

package com.huang.controller;

import com.huang.message.Info;
import com.huang.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@RestController
@Api(tags = "用户数据接口")
@RequestMapping("user")
public class UserController

    @Autowired
    private Info info;
    @Autowired
    private UserService userService;

    @ApiOperation(value="用户登录"，notes="用户登录")
    //获取前端微信登录传来的user信息
    @GetMapping("login/mailAddr")
    @APiImplicitParam(paramType = "path",name="mailAddr",value="用户邮箱".required = true)
    @ApiResponse(code = 200,message = "登录成功!")
    @ApiResponse(code = 500,message = "登录失败!")
    public Info login(@PathVariable("mailAddr") String mailAddr) 
        return userService.login(mailAddr);
    

以User实体类对象为例

Swagger2注解不仅可以用在controller上，还可以用在实体类的描述中

• @APiModel注解用与配置该实体类的相关信息，可以添加解释和描述
• @APiModelProperty注解用于配置实体类对象的属性信息

package com.huang.entity;

import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.experimental.Accessors;

import java.util.Date;

@Data
@NoArgsConstructor
@AllArgsConstructor
@Accessors(chain = true)
@APiModel(value="用户实体类",description="用户信息描述类")
public class User

	@APiModelProperty(value="用户id")
    private String userId;
    private String username;
    private String mailAddr;
    private String password;
    private String sex;
    private Date birthday;
    private String portraitUrl;
    private String province;
    private String city;
    private String profile;

通过以上代码，就基本上完成了对Swagger2接口文档的配置，之后便可以根据需求自动生成接口文档了。启动Spring Boot项目，访问localhost:8080/swagger-ui.html，就可以查看对应的接口文档，并且接口文档还可以根据用户新添加的controller实时更新

三、总结

本次的博客从前后端对接角度分析了本项目是如何通过搭建Swagger2实现自动维护API接口文档，希望在未来的项目实训或企业开发中，能够使用上这套技术，可以使接口文档的维护变得更加便捷。希望在未来对项目的分析中能收获更多有关项目开发的知识，在这个过程中也感谢老师的指导与帮助。