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 依赖管理

 <!-- swagger-mvc -->
    <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指明是否为必须

效果