Spring MVC学习总结（8）——Swagger入门详解

2023-08-27 11:32:04

前言

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码，了解更多内容，见参考资料。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger
让部署管理和使用功能强大的API从未如此简单。

一、使用介绍

什么是 Swagger?

Swagger™的目标是为REST APIs 定义一个标准的，与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。

浏览 Swagger-Spec 去了解更多关于Swagger
项目的信息，包括附加的支持其他语言的库。

如何集成Swagger-springmvc到我们的项目中?

依赖：

Maven

<dependency><groupId>com.mangofactory</groupId><artifactId>swagger-springmvc</artifactId><version>0.9.4</version></dependency>

Gradle

repositories {jcenter()}compile "com.mangofactory:swagger-springmvc:0.9.4"

使用：

要最快捷地启动swagger-springmvc项目并且使用默认设置，推荐的方式是使用SwaggerSpringMvc插件

Spring Java Configuration

@Configuration@EnableWebMvc@EnableSwagger

@ComponentScan("com.myapp.packages")

public class WebAppConfig { ...}

Spring xml Configuration

<mvc:annotation-driven/>

<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />

SwaggerSpringMvcPlugin XML Configuration

为了使用这个插件，你需要创造一个spring Java配置类。使用spring的
@Configuration ，这个配置类必须被定义到你的xml上下文

<mvc:annotation-driven/>

<beanclass="com.yourapp.configuration.MySwaggerConfig"/>

@Configuration@EnableSwagger

//Loads the spring beans required by the framework

public class MySwaggerConfig {

private SpringSwaggerConfig springSwaggerConfig;

/*** Required to autowire SpringSwaggerConfig*/

@Autowired

public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig)
{

this.springSwaggerConfig = springSwaggerConfig;

}

/*** Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc framework - allowing
for multiple* swagger groups i.e. same code base multiple swagger resource listings. */

@Beanpublic SwaggerSpringMvcPlugin customImplementation(){

return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).includePatterns(".*pet.*");}}

SwaggerSpringMvcPlugin Spring Java Configuration

使用@EnableSwagger注解

自动注入SpringSwaggerConfig

定义一个或多个SwaggerSpringMvcPlugin实例，通过springs @Bean注解

@Configuration@EnableWebMvc

@EnableSwagger

@ComponentScan("com.myapp.controllers")

public class CustomJavaPluginConfig {

private SpringSwaggerConfig springSwaggerConfig;

@Autowired

public void setSpringSwaggerConfig(SpringSwaggerConfigspringSwaggerConfig{

this.springSwaggerConfig = springSwaggerConfig;

}

@Bean

//Don't forget the

@Bean annotationpublic SwaggerSpringMvcPlugin customImplementation(){
return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo()).includePatterns(".*pet.*");

}

private ApiInfo apiInfo() {

ApiInfo apiInfo = new ApiInfo(

"My Apps API Title",

"My Apps API Description",

"My Apps API terms of service",

"My Apps API Contact Email",

"My Apps API Licence Type",

"My Apps API License URL" );

return apiInfo;}}

二、碰到的问题

关于@API注解