前后端分离：SpringMVC中使用Swagger

最新推荐文章于 2022-05-31 15:20:53 发布

张富涛

最新推荐文章于 2022-05-31 15:20:53 发布

阅读量1.6k

点赞数

分类专栏：前后端分离文章标签： java 后端 swagger2 前端

本文链接：https://blog.csdn.net/zhangft7478191/article/details/114097051

版权

前后端分离专栏收录该内容

3 篇文章 0 订阅

订阅专栏

这是张富涛的第15篇原创

前后端分离：SpringMVC中使用Swagger

我们在上篇文章《前后端分离：Swagger,生成接口文档的工具》中已经介绍了Swagger的诸多优点。Swagger基本支持所有语言，但最重要的是它可以在Java中与SpringMVC完美结合！那么这篇文章就介绍如何在SpringMVC中使用Swagger！

1. 导入Swagger包

如果是Maven项目，将在pom.xml文件中写入如下配置：

<!-- Swagger -->
<dependency>
   <groupId>io.swagger</groupId>
   <artifactId>swagger-core</artifactId>
   <version>1.5.8</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.4.0</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.4.0</version>
</dependency>

如果非Maven项目，可直接下载对应版本Jar包导入项目即可。

2. 创建配置文件

在项目中创建“SwaggerConfiguration”和“SwaggerWebMvcConfigurerAdapter”配置文件。项目目录结构可与下图不同（可不必一定在config目录下）。

SwaggerConfiguration文件内容如下图所示：

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

SwaggerWebMvcConfigurerAdapter文件内容如下图所示：

@Configuration
@EnableWebMvc
@ComponentScan(basePackages = "com.swaggerdemo.controller")
public class SwaggerWebMvcConfigurerAdapter extends WebMvcConfigurerAdapter {
    @Bean
    public ViewResolver viewResolver() {
        InternalResourceViewResolver viewResolver = new InternalResourceViewResolver();
        viewResolver.setViewClass(JstlView.class);
        viewResolver.setPrefix("/WEB-INF/views/");
        viewResolver.setSuffix(".jsp");
        return viewResolver;
    }


    @Bean
    public MessageSource messageSource() {
        ResourceBundleMessageSource messageSource = new ResourceBundleMessageSource();
        messageSource.setBasename("messages");
        return messageSource;
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        super.addResourceHandlers(registry);

        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
    @Override
    public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
        configurer.enable();
    }
}

其中 @ComponentScan 注解的basePackages属性需要填写Controller所在路径。

我们要保证Spring能够扫描到我们的配置信息，在Spring或SpringMVC中配置如下图（可单独制定路径）。

<context:component-scan base-package="com.swaggerdemo"/>

运行程序后我们就可以在项目根路径下访问到swagger-ui.html页面了，地址如：http://localhost:8080/SwaggerDemo/swagger-ui.html。

3. Swagger的使用

Swagger通过注解生成API文档，我们只需要在方法和实体类上增加简单的注解即可做到。

我们先来看看Swagger的主页：

要想Swagger扫描到上图的Controller，需要在Controller中的类名上加入@Controller，同时Controller的简介需要用到Swagger提供的@Api 注解：

实际写法：

@Controller
@RequestMapping("/login")
@Api(tags = "用户注册登录")
public class LoginController {
    ....
}

这样就可以在生成的页面上展示相应的文档内容了。

3.1. swagger常用注解

下面介绍Swagger的几个常用注解，包含我们上文所展示的@Api还有其他几个注解：

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段

@ApiOperation注解具体应用：

这个注解会在Swagger页面中的单个方法生成对应“方法访问动词”、“方法简述”、“方法详细描述”。

@ApiParam注解具体应用：

针对每个参数增加注解@ApiParam，会在Swagger测试页面中生成对应“参数名”、“参数说明”、“参数类型”。这些有助于进行单元测试，非常实用！

@ApiModel和@ApiProperty注解具体应用：

当我们需要用一个对象作为接收参数或者返回值时，Swagger也准备了对应的注解供我们使用，当我们创建一个Bean类作为规定返回值结构时：

最终的结果是在Swagger规定某个方法的返回值时可以展示其具体信息：

点击 Model Schema可以展示具体结构：

同时当我们将声明好的对象作为参数传递时，Swagger也能对参数进行解析，便于单元测试，如我们添加一个收货地址类(省略get&set方法)：

/**
 * 收货地址实体类
 * Created by zhangft on 2016/11/18.
 */
@ApiModel("收货地址")
public class Address {
    /**
     * 收货地址ID唯一标识
     */
    @ApiModelProperty(value = "收货地址ID唯一标识", required = true)
    private int address_id;
    /**
     * 用户ID
     */
    @ApiModelProperty(value = "用户ID", required = true)
    private String user_id;
    /**
     * 物理地址
     */
    @ApiModelProperty(value = "物理地址", required = true)
    private String detailed_address;
    /**
     * 经度
     */
    @ApiModelProperty(value = "经度", required = true)
    private double longitude;
    /**
     * 纬度
     */
    @ApiModelProperty(value = "纬度", required = true)
    private double latitude;

然后我们将其作为参数：

最终的Swagger会生成如下界面：

Swagger会将其参数完全解析出来，很棒吧！

4. Swagger生成API文档原理

那么，这么强大的Swagger是如何生成API文档的呢？

其实Swagger是通过程序中的注解生成Swagger需要的Json串，然后静态页面通过解析Json串生成我们要的API文档。这也是本文开篇时所说的，为什么Swagger基本能支持所有语言的原因！本质上，Swagger是依赖Json串进行展示的。
那么Swagger所依赖的Json串到底是什么样子呢？我大概截一部分图来展示吧！

原始文档为：

5. Swagger的其他产品

我们之前所介绍的都是Swagger-UI，那么Swagger还有能对Swagger串进行编辑的工具并展示视图的Swagger Editor 。还有能生成不同平台客户端代码的Swagger Codegen。

同时swagger也经过多年后推出了一些面向企业级的产品。

swagger官方地址：https://swagger.io/

ps：本文作于2017年06月，随着时间推移，swagger也有非常大的更新，如api和程序版本，您可以继续使用本文介绍版本进行开发，但也可以在网上寻找最新版本。感谢您的阅读和理解，如果本文给您带来思路上的帮助或帮助您了解swagger，将是对我非常大的鼓励！

---------------

公众号：张富涛的学习笔记(ID:futaoNT)

知乎：张富涛

CSDN：张富涛

这是一个在夜晚可以靠编程拯救世界的程序员，关注他将在第一时间获悉他的知识、工作心得！

长按下图二维码关注：

张富涛

关注

0
点赞
踩
3

收藏

觉得还不错? 一键收藏
1
评论
前后端分离：SpringMVC中使用Swagger

这是张富涛的第15篇原创前后端分离：SpringMVC中使用Swagger我们在上篇文章《前后端分离：Swagger,生成接口文档的工具》中已经介绍了Swagger的诸多优点。Swagger基本支持所有语言，但最重要的是它可以在Java中与SpringMVC完美结合！那么这篇文章就介绍如何在SpringMVC中使用Swagger！1. 导入Swagger包如果是Maven项目，将在pom.xml文件中写入如下配置：<dependency&g.
复制链接

扫一扫