Swagger

1、swagger学习
Swagger定义
Swagger同类工具
Swagger和web项目结合
Swagger在公司项目中如何应用

2、Swagger定义
Swagger官网：http://swagger.io
GitHub地址：https://github.com/swagger-api
官方注解文档：http://docs.swagger.io/swagger-core/apidocs/index.html
Swagger-UI地址：https://github.com/swagger-api/swagger-ui
概念：
A Powerful Interface to your API
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。 Swagger 让部署管理和使用功能强大的API从未如此简单。
2.1 Swagger子项目
Paste_Image.png
其实swagger是一个比较大的项目，就像spring一样，他下面有很多模块，我们现在只需要使用它的UI模。

3、相关学习博客
在线Demo: http://petstore.swagger.io
swagger学习分享： http://www.mamicode.com/info-detail-525592.html
InfoQ视频：http://www.infoq.com/cn/presentations/use-swagger-create-rest-api-document?utm_source=tuicool&utm_medium=referral
< http://hao.jobbole.com/swagger/>
Swagger文档： http://www.scalatra.org/2.2/guides/swagger.html
swagger博客-：http://ningandjiao.iteye.com/blog/1948874
swagger博客二： http://www.jianshu.com/p/0465a2b837d2
Swagger博客三： http://javatech.wang/index.php/archives/74/
Swagger案例: http://petstore.swagger.io/#!/user/createUser
4、swagger和springmvc整合
4.1 依赖管理

<dependency>
  <groupId>com.mangofactory</groupId>
  <artifactId>swagger-springmvc</artifactId>
  <version>1.0.2</version>
</dependency>
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
  <version>2.4.2</version>
</dependency>
<!-- swagger-mvc -->

4.2 Swagger配置
Swagger的配置最终就是配置一个config类，通过Java编码的方式实现配置：

@Configuration
@EnableSwagger
public class SwaggerConfig {

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.
 */
@Bean
public SwaggerSpringMvcPlugin customImplementation()
{
    return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
            .apiInfo(apiInfo())
            .includePatterns(".*?");
}

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;
}

}

这个是个模板，里面内容可以自己定义，修改基本上是对apiinfo自定义数据。
在spring中注入Bean：
<context:component-scan base-package=“net.shopin.swagger”/>

swagger基本就算是配置好了，剩下的事情就是接口编写和展示了。

引入swagger-UI组件
更改项目文档路径

Paste_Image.png
修改index.html文件中的路径：默认是从连接http://petstore.swagger.io/v2/swagger.json获取API的JSON,我们改为 http://{ip}:{port}/{projectName}/api-docs 的形式，也就ip:端口号/项目名/api-docs

Paste_Image.png
最后就是对controller的书写：

@Api(value = “product”, description = “商品管理”, produces = MediaType.APPLICATION_JSON_VALUE)
@Controller
public class ProductController {

@Autowired
private ProductService productService;

@ApiOperation(value = "获得商品信息", notes = "获取商品信息(用于数据同步)", httpMethod = "POST", produces=MediaType.APPLICATION_JSON_VALUE)
@ApiResponses(value = {@ApiResponse(code = 200, message = "商品信息"),
    @ApiResponse(code = 201, message = ErrorType.errorCheckToken + "(token验证失败)",  response=String.class),
    @ApiResponse(code = 202, message = ErrorType.error500 + "(系统错误)",response = String.class)})
@RequestMapping(value = RestUrl.getProduct, method = RequestMethod.POST)
@ResponseBody
public ResultDTO<Products> getProduct(@ApiParam(value = "json参数",  required = true) @RequestBody BaseParam param)throws Exception {
    return productService.getProduct(param);
}

}

@API：表示一个开放的API，可以通过description简明的描述API的功能，produce指定API的mime类型
一个@API下，可以有多个@ApiOperation,表示针对该API的CRUD操作，在ApiOperation Annotation中还可以通过value，notes描述该操作的作用，response描述正常情况下该请求返回的对象类型
在一个@ApiOperation下，可以通过@ApiResponses描述API操作可能出现的异常情况
@ApiParam用于描述该API操作接收的参数类型，value用于描述参数，required指明参数是否为必须。
@ApiModelProperty中，value指定描述，required指明是否为必须
效果

Paste_Image.png

作者：橙小张
链接：https://www.jianshu.com/p/4115f2b53983
来源：简书
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。