Swagger

最新推荐文章于 2022-06-27 18:34:29 发布

linyuxb123

最新推荐文章于 2022-06-27 18:34:29 发布

阅读量454

点赞数 2

分类专栏： java语言工具使用

java语言同时被 2 个专栏收录

28 篇文章 1 订阅

订阅专栏

工具使用

26 篇文章 0 订阅

订阅专栏

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

效果