Swagger框架学习分享

转至元数据结尾
转至元数据起始

一、背景介绍

1.1.项目简介

Swagger项目是由Dilip Krishnan和Adrian Kelly等人维护开发的一个为Spring Web MVC 项目提供方法文档的一个框架。该框架最主要的功能是将Controller的方法进行可视化的展现,像方法注释,方法参数,方法返回值等都提供了相应的用户界面,尤其是对JSON参数的支持。同时可以结合swagger-ui可以对用户界面进行不同程度的定制,也可以对方法进行一个简单的测试。

1.2.code repository

1.3.演示项目

二、开发准备

2.1.环境准备

  • idea intellij 13+
  • Oracle java 1.6
  • Gradle 2.0 +

2.2.项目搭建

2.2.1.jar仓库

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.0</version>
</dependency>

Gradle

repositories {
    jcenter()
}
 
compile "com.mangofactory:swagger-springmvc:1.0.0"

2.2.2.相关依赖

  • As of v0.9.5 all dependencies on scala have been removed.
  • Spring 3.2.x or above
  • jackson 2.4.4
  • guava 15.0

2.2.3.编写配置文件

编写一个Java文件,并使用注解:

  • @Configuration 配置注解,自动在本类上下文加载一些环境变量信息
  • @EnableWebMvc 
  • @EnableSwagger 使swagger生效
  • @ComponentScan("com.myapp.packages") 需要扫描的包路径

示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
package org.bugkillers.back.swagger;
 
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.paths.SwaggerPathProvider;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
/**
 * 使用注解的方式来扫描API
 * 无需在Spring的xml配置文件来配置,由 @see @EnableWebMvc 代替
 * <p/>
 * <p> @author 刘新宇
 *
 * <p> @date 2015年1月30日 下午1:18:48
 * <p> @version 0.0.1
 */
@Configuration
@EnableWebMvc
@EnableSwagger
@ComponentScan(basePackages ={"com.ak.swaggerspringmvc.shared.controller""com.ak.spring3.music"})
public class CustomJavaPluginConfig extends WebMvcConfigurerAdapter {
   private SpringSwaggerConfig springSwaggerConfig;
   @Autowired
   public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
      this.springSwaggerConfig = springSwaggerConfig;
   }
   /**
    * 链式编程 来定制API样式
    * 后续会加上分组信息
    * @return
    */
   @Bean
   public SwaggerSpringMvcPlugin customImplementation(){
      return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
            .apiInfo(apiInfo())
            .includePatterns(".*")
//            .pathProvider(new GtPaths())
            .apiVersion("0.0.1")
            .swaggerGroup("user");
   }
    private ApiInfo apiInfo() {
      ApiInfo apiInfo = new ApiInfo(
              "bugkillers-back API",
              "bugkillers 后台API文档",
              "<a href=#>,
              "bugkillers@163.com",
              "My License",
              "My Apps API License URL"
        );
      return apiInfo;
    }
    @Override
    public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
      configurer.enable();
    }
     
    class GtPaths extends SwaggerPathProvider{
        @Override
        protected String applicationPath() {
            return "/restapi";
        }
        @Override
        protected String getDocumentationPath() {
            return "/restapi";
        }
    }
     
}

 

 也可以自己不写配置类,直接使用默认的实现类,在Spring的配置文件中共配置:(不推荐

1
2
<mvc:annotation-driven/> <!-- Required so swagger-springmvc can access spring's RequestMappingHandlerMapping  -->
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />

 

2.2.4.与swagger-ui集成

方式一:

  • Note: Only use this option if you don't need to customize any of the swagger-ui static content, otherwise use option 2.
  • Use the web-jar which packages all of the swagger-ui static content.
  • Requires that your app is using the servlet 3 specification.
  • For non-spring boot applications some extra spring configuration (ResourceHandler's) is required. See: https://github.com/adrianbk/swagger-springmvc-demo/tree/master/swagger-ui
1
2
3
4
dependencies {
  ...
  compile "org.ajar:swagger-spring-mvc-ui:0.4"
}

方式二:(推荐

  • Manually copy all of the static content swagger-ui's dist directory (https://github.com/wordnik/swagger-ui/tree/master/dist)
  • Provide the necessary view resolvers and resource handlers to serve the static content.
  • Consult the spring documentation on serving static resources.

The following is one way to serve static content from /src/main/webapp

1
2
3
4
5
<!-- Direct static mappings -->
<mvc:resources mapping="*.html" location="/"/>
 
<!-- Serve static content-->
<mvc:default-servlet-handler/>

2.6.5.Controller配置

使用注解对Controller进行配置:

  • @Api 配置方法API
  • @ApiOperation API的操作 GET PUT DELETE POST
  • @ApiParam API的方法参数描述

示例Controller:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
package org.bugkillers.back.user.controller;
import java.util.List;
import org.bugkillers.back.bean.User;
import org.bugkillers.back.result.Result;
import org.bugkillers.back.user.service.UserService;
import org.bugkillers.back.util.ResultUtil;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiOperation;
import com.wordnik.swagger.annotations.ApiParam;
/**
 * 用户操作Controller
 * <p/>
 * <p>
 *
 * @author 刘新宇
 *
 *         <p>
 * @date 2015年1月30日 上午10:50:34
 *       <p>
 * @version 0.0.1
 */
@Api(value = "user-api", description = "有关于用户的CURD操作", position = 5)
@Controller
@RequestMapping("/user")
public class UserController {
    @Autowired
    private UserService service;
    /**
     * 注册用户
     * @param user
     */
    @ApiOperation(value = "注册", notes = "注册用户", position = 3)
    @ResponseBody
    @RequestMapping(value = { "/regist" }, method = RequestMethod.POST)
    public ResponseEntity<?> regist(@RequestBody User user) {
        service.save(user);
        Result<String> result = ResultUtil.buildSuccessResult("注册成功");
        return new ResponseEntity<Result<String>>(result, HttpStatus.OK);
    }
     
    /**
     * 根据pk查找用户
     * @param userPk
     * @return
     */
    @ApiOperation(value = "根据pk查找用户", notes = "返回用户实体对象", response = User.class, position = 2)
    @ResponseBody
    @RequestMapping(value = { "/{userPk}" }, method = RequestMethod.GET)
    public ResponseEntity<?> findByPk(
            @ApiParam(value = "填写Pk", allowableValues = "range[1,5]", required = true, defaultValue = "userPk", allowMultiple = true@PathVariable("userPk") Integer userPk) {
        Result<User> result = ResultUtil.buildSuccessResult(service.findByPk(userPk));
        return new ResponseEntity<Result<User>>(result, HttpStatus.OK);
    }
     
    /**
     * 测试
     * @param who
     * @return
     */
    @ApiOperation(value = "Hellow World", notes = "测试功能", position = 1)
    @ResponseBody
    @RequestMapping(value = { "/hello/{who}" }, method = RequestMethod.GET)
    public ResponseEntity<?> hello(
            @ApiParam(value = "填写名称"@PathVariable("who") String who) {
        Result<String> result = ResultUtil.buildSuccessResult( "Hello guys" " " + who + "!");
        return new ResponseEntity<Result<String>>(result, HttpStatus.OK);
    }
    /**
     * 查询所有
     * @return
     */
    @ApiOperation(value = "获取所有用户", notes = "返回用户实体对象集合", position = 5)
    @RequestMapping(value = "/findAll", method = RequestMethod.GET)
    public @ResponseBody ResponseEntity<?>  findAll() {
        Result<List<User>> result = ResultUtil.buildSuccessResult( service.findAll());
        return  new ResponseEntity<Result<List<User>>>(result, HttpStatus.OK);
    }
     
    /**
     * 根据用户pk更新实体
     * @param userPk  用户pk
     * @param user 返回更新后的实体
     * @return
     */
    @ApiOperation(value = "更新用户", notes = "返回更新的用户实体对象",position = 5)
    @RequestMapping(value = "/update/{userPk}", method = RequestMethod.PUT)
    public ResponseEntity<?> updateByPk(
            @PathVariable("userPk") Integer userPk, @RequestBody User user) {
        user.setPk_user(userPk);
        service.update(user);
        Result<User> result = ResultUtil.buildSuccessResult(user);
        return new ResponseEntity<Result<User>>(result, HttpStatus.OK);
    }
     
    /**
     * 根据用户pk删除实体
     * @param userPk  用户pk
     * @return
     */
    @ApiOperation(value = "删除用户", notes = "根据pk删除用户",position = 5)
    @RequestMapping(value = "/delete/{userPk}", method = RequestMethod.GET)
    public ResponseEntity<?> deleteByPk(
            @PathVariable("userPk") Integer userPk) {
        service.delete(userPk);
        Result<String> result = ResultUtil.buildSuccessResult("删除成功");
        return new ResponseEntity<Result<String>>(result, HttpStatus.OK);
    }
}
 
 

2.2.6.启动中间件

项目配置了Jetty或者Tomcat等Web容器的话,在对应的Controller配置好的话就可以启动看效果了。

2.2.7.需求定制

  • 分组信息定制
  • Url定制
  • Http相应定制

 

三、学习感想

Swagger很好的为我们在开发RESTful框架应用时,前后台分离的情况下提供了很有效的解决方案,上手迅速,操作简单,界面精简,功能完善,满足各种定制化的需求,是在使用Spring MVC做Web开发时的不二选择。通过对swagger的学习,增强了英语交流的能力,改变了以前的学习方法,收获了很多,同时也也得感谢国外友人的悉心帮助~技术无国界~


在公司的Wiki上写的博文,因为外面访问不了公司的内网,故贴过来给需要的小伙伴们分享一下。



本页内容版权归属为原作者,如有侵犯您的权益,请通知我们删除。

搭框架遇到的一些问题 - 2015-04-15 20:04:28

问题一:HTTP错误50019-Internal Service Error 原来是之前先安装VS,再安装IIS的原因。所以我们要对IIS进行配置。 方法一:直接在DOS窗口里面注册下AspNet:如图。   方法二: IIS :IIS和Framework的安装顺序不对, 所以我们可以卸载重新安装。(笨方法)  方法有很多,大家可以在网上找到答案。 问题二:HTTP 错误 404.3 - Not Found 问题原因:系统是win8.1的,而IIS的版本是8.5(在IIS里的帮助:关于Internet信息
希望了解的各位讨论一下。               前几天手贱+强迫症,趁在家网速好,update和upgrade了ubuntu,结果导致无法进入系统,登陆界面输入密码后一直卡主,在内网外网找了N多解决办法,折腾了一天多还是无解,只能重新装。无奈,caffe的环境又得重新配置一遍。        但是在重装NVIDIA驱动的时候发现了一条注意事项: 每次升级内核后需要重新编译一次显卡驱动。。。受限制驱动列表(源)那种倒是没事。       不知 无法开机 是否因为没有重新编译显卡驱动就upgrade升级
(1)ES- Elementary Streams ( 原始流 ) ,对视频、音频信号及其他数据进行编码压缩后的数据流称为原始流。原始流包括访问单元,比如视频原始流的访问单元就是一副图像的编码数据。 (2) PES-Packetized Elementary Streams ( 分组的原始流 ) ,原始流形成的分组称为 PES 分组,是用来传递原始流的一种数据结构 (3) 节目是节目元素的集合。 节目元素可能是原始流,这些原始流有共同的时间基点,用来做同步显示。 (4) 传输流和节目流 TS-Transp

安装一套OCS inventory-ng 环境 - 2015-04-15 20:04:14

安装一套OCS inventory-ng 环境 官网 : http://www.ocsinventory-ng.org/en/ 首先安装Server 相关的包在官网上下载即可 我下载的是 OCSNG_UNIX_SERVER-1.02.3.tar.gz 我使用SecureCRT连接我的linux测试机 用rz上传到对应的目录,我安装在 /usr/local/ 然后解压  tar -zxvf OCSNG_UNIX_SERVER-2.1.2.tar.gz  cd OCSNG_UNIX_SERVER-2.1.2
原始文章:http://www.csdn.net/article/2015-01-15/2823577  订单号去重的问题:假设A节点向B节点发送新订单请求,但是网络有可能失败,则这个分布式事务有可能出现B节点上已经成功执行,但是A却以为失败了,导致重新发送订单请求,造成重复的订单 要点:关键问题是订单号这一ID信息要防止重复生成,如果ID号能够提前生成的话,就可以在每次发送这一ID信息,使得请求的每次处理做到幂等。 因此,JD现在的方案相当于在B节点上根据商品信息、客户信息等等,做了一个到订单ID的反向
cached根据protobuf的元数据机制去保存和读取数据库中的数据。 为了简化服务器交互的复杂度,逻辑服务器用的protobuf和cached的protobuf,数据结构要完全一致。 不一致的话,会出现不确定的错误。比如,逻辑服务器用Msg1序列化数据,传给cached, cached却用Msg2去解析,重组,保存到DB。结果就全乱了! 所以,逻辑服务器连接cached成功后,先要保证protobuf是一致的。 1. logicd从cached获取Message名字列表和所有Message的总MD5

Linux命令学习篇0——由来 - 2015-04-15 11:04:30

昨天 在用curl发送简单的HTTP请求做测试的时候发现自己每次使用的时候都是在网络上查看别人的示例才能想起来怎么用,这样效率太低了,虽然有网络依然在,但是总感觉不是被自己掌握着,心里不踏实,回想起来自己使用Linux也差不多有三四年了,从最开始接触就是用一本Linux基础教程的书籍(不是鸟哥的书),开始接触的就是linux的各种各样的命令一些关于简单的shell编程的知识,但是当时仅仅掌握了一些常用的命令,对于大多数的命令还是在使用的时候遇到再翻资料查看,可能处于对英文文档的畏惧或是感到乏味,通过man
CentOS 6 部署 Nginx + PHP5 Web服务器 在 CetnOS 6 (64位) 操作系统上部署Nginx and PHP5服务器。这个过程通过 yum 命令进行RPM包安装。 可以参考 PHP 官方文档 。 安装 一些必要的 YUM 库 root 用户执行: # rpm -Uvh http://dl.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm # rpm -Uvh http://rpms.famillec

【ITOO】WCF宿主的几种方式 - 2015-04-15 11:04:06

            上篇博客已经说明了 WCF 的一个服务如何创建,那么创建好了服务之后,我们如何发布出去呢?要想完整的做完一个 WCF 服务,一共分三步走,第一步就是像上篇博客所说创建服务,第二步是发布服务,还有最后一步就是客户端调用服务。今天重点说发布服务。说到发布,不得不说一下 WCF 的宿主。说到宿主,又不得不说一下 Endpoint 。   首先,宿主是什么?            通俗的说就是,当我们写好了一个服务之后,要有地方放它,才能让客户端调用的时候找到它,这就是宿主,它是一种媒介,

VS2012添加单元测试 - 2015-04-15 11:04:05

    在搞白盒测试的过程中,想要加入单元测试选项,右击-选项 会看到下图:    下面我来讲一下解决方法: 1.工具 -- 自定义 2.上下文菜单 -- 编辑器上下文菜单 | 代码窗口: 3.将“创建单元测试”移到运行测试菜单下面 4.关闭 VS 并重启       重启→对着类名点击右键,出现灰色“创建单元测试”按钮 5.解决方案中右键→添加→新建项目→单元测试项目。 6.效果图如下: 7.右键单元测试项目→添加→单元测试 8.返回非测试项目项目→类名,点击右键→ 创建单元测试 9.注意:如重新打开项