位置：首页-资讯-后端开发

关于使用swagger整合springMVC的方法

2023-05-17 20:04

短信预约 -IT技能 免费直播动态提醒

前文：

在日常工作中，开发人员经常会遇到写接口文档的工作，一般都是word文档，带来书写麻烦、维护麻烦的问题，比如改了源代码忘了更新文档、解释不明确带来歧义、无法在线尝试等等。swagger就是为了解决这些问题而产生的。这是官方的例子，截图如下

swagger原理

后台：后端部分与java集成，后最终会产生一个json文件。

前台：前台部分就是html、css、js文件，js利用后台产生的json文件构造api；

前台配置：

去https://github.com/swagger-api/swagger-ui 下载zip包，解压后，将dist文件夹下的所有内容copy到，java web project的webapp下，比如，

maven依赖：

<repositories>
    <repository>
      <id>jcenter-release</id>
      <name>jcenter</name>
      <url>http://oss.jfrog.org/artifactory/oss-release-local/</url>
    </repository>
</repositories>
 
<dependency>
    <groupId>com.mangofactory</groupId>
    <artifactId>swagger-springmvc</artifactId>
    <version>1.0.1</version>
</dependency>

后台配置：

途径一：

在spring的applicationcontext.xml文件中，添加配置

 <mvc:annotation-driven/>
    <bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
    <!-- 对包中的所有类进行扫描，以完成Bean创建和自动依赖注入的功能 稍后会创建该包：webmvct.cmd -->    
	<context:component-scan base-package="webmvct.cmd"/>

解释：swagger会扫描 base-package包下的所有类，生成api文档

将docapi文件下的index.html文件，url改为本工程的路径，如下图，

截止到现在，最简单的swagger配置已经完成。访问 //localhost:8080/hi/docapi/index.html 就可以看到效果。

途径二：

如果想进一步的定制，比如只扫描某个包下的某些路径，那么就需要用到定制类，途径二是基于途径一在功能上的扩展，所以要想达到定制效果首先将途径一配置好。

创建swaggerspringconfig定制类，比如

@Configuration
@EnableSwagger //Loads the spring beans required by the framework
@ComponentScan("com.test")
public class MySwaggerConfig {
	private SpringSwaggerConfig springSwaggerConfig;
 
	   
	   @Autowired
	   public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
	      this.springSwaggerConfig = springSwaggerConfig;
	   }
 
	   
	   @Bean
	   public SwaggerSpringMvcPlugin customImplementation(){
	      return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
	      .includePatterns(".*store.*");
	      
	   }
 
}

@componentscan，将com.test包下的类也包含在内进行扫描；

customImplementation方法的includePatterns可以进行过滤，只include含有store的路径

controller类的样例：

@Api(value="/store",description="商店")
@Controller
@RequestMapping("/store")
public class StoreController {
	
	
	@RequestMapping(value = "/{storeid}",method=RequestMethod.GET)
	@ResponseBody
	@ApiOperation(value="获取商店信息",notes="通过商店id获取商店信息")
	public Store getStore(String storeid){
		return new Store();
	}
	
	@ApiOperation(value="获取商店信息",notes="通过商店name获取商店信息")
	@ResponseBody
	@RequestMapping(value = "/{storename}",method=RequestMethod.POST)
	public Store getStore2(String storeid){
		return new Store();
	}
}

@api，用在类上，用于解释整个类。

@apioperation，用于方法上，value是笼统的介绍方法作用，notes是详细的说明方法作用

最终效果图：