# swagger-maven-plugin

**Repository Path**: xinlan1964/swagger-maven-plugin

## Basic Information

- **Project Name**: swagger-maven-plugin
- **Description**: swagger-maven-plugin 修改扩展
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 2
- **Created**: 2016-04-16
- **Last Updated**: 2022-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

swagger-maven-plugin用来扫描类生成swagger.json规范。基于支持JAX-RS和SpringMVC。注意：  
1. 扫描@Api注解的类；  
2. 只有@ApiOperation,@RequestMapping注解并带有method属性的方法才会被识别；  
3. 带@ApiParam注解的参数才会被识别；  
4. SpringMVC扫描参数识别类型规则：逻辑在SpringSwaggerExtension  
|  springMVC注解	| 参数类型  					|  
|---------------|---------------------------|  
| RequestParam  |QueryParameter 	query   |    
| PathVariable  |PathParameter  	path  	|  
| RequestHeader |HeaderParameter header  	|  
| CookieValue   |CookieParameter cookie  	|  
| RequestPart   |FormParameter  	formData|    
| ModelAttribute|QueryParameter 	query  	|  
| 其他 			|  BodyParameter 	body  	|  
5. maven插件的配置参数需要包括：info, info/title, info/version, locations(需要生成规范的类名/包名)  
6. 参数的schema属性是object类型并properties为空，swaggerui会报错:如参数是Object类型，

##swagger-maven-plugin修改扩展
swaggerUI生成的doc文档比javadoc文档更容易在团队中传阅交流。 
  
工程在集成构建时把生成的swagger规范文件上传到指定目录swagger-dir，带swaggerUI的基础web应用会扫描swagger-dir目录，返回swagger.json的列表到页面。swagger-maven-plugin只针对REST API，对于普通API需要另做处理：新增继承AbstractDocumentSource的PSMavenDocumentSource，继承AbstractReader的PSApiReader。  
修改点：  
1. 默认增加一个类全名的tag标签；  
2. springMVC默认method=post,如果@RequstMapping中没有写明method的方法也可以识别；  
3. 对于非REST的API，默认path为方法签名，默认method为post  
4. @ApiParam没写明name属性则自动识别，在此使用`String[] org.springframework.core.ParameterNameDiscoverer.getParameterNames(Method method)`  
5. 增加插件配置参数：swaggerFileName指定生成的swagger规范的文件名