Swagger工具介绍及整合web框架教程

Swagger 介绍

Swagger [swægə]

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的接口文档。

Swagger 官网

swagger官网提供了四个工具： Swagger Editor、Swagger Codegen、Swagger UI和Swagger Inspector。

Swagger Editor：基于Swagger的API的开源编辑器上设计、描述和记录您的API。Swagger编辑器非常适合快速开始使用Swagger规范。它干净，高效，并配备了许多功能。

注：即使工具已经减轻了很多工作量，但是json文档写起来还是一个很繁琐的事情，于是乎，就有大神开发出了可以嵌入代码中直接生成json文档的工具，后面会介绍两种：Swagger整合Jersey和Swagger整合Spring MVC

Swagger Codegen：暂时还不清楚，有人了解可以留言给我，谢谢~

Swagger UI：根据Swagger规范生成的json文档转化成可视化前端界面。

Swagger Inspector：用来调用和验证REST、GraphQL和基于SOAP的Web服务，以确保它们正确运行。（和另一个名叫Postman工具相似，感兴趣的可以研究研究）

整合Swagger和Jersey

第一步 在项目中加入依赖

compile(group: 'io.swagger', name: 'swagger-jersey2-jaxrs', version: '1.5.0') {
        exclude module: 'jackson-datatype-joda'
    }

第二步 在程序用引入swgger注解

在程序中对应的Controller类中使用swagger注解，这里只展示最常用的几个，更加详细的参数信息可以在官网上查询。

@Api("User")
@Path("users")
public class UserApi {

  @Autowired
  private UserService userService;

  // 增
  @ApiOperation(value = "新增用户")
  @POST
  // 返回类型
  @Produces(MediaType.APPLICATION_JSON)
  //传入类型
  @Consumes(MediaType.APPLICATION_JSON)
  public Response addUser(UserDTO userDTO) {
    userService.addUser(userDTO);
    return Response.ok().build();
  }

  // 删
  @ApiOperation(value = "删除用户")
  @Path("{user_id}")
  @DELETE
  @Produces(MediaType.APPLICATION_JSON)
  public void deleteUser(@PathParam("user_id") String userId) {
    System.out.println("删除"+userId);
  }

  // 改
  @ApiOperation(value = "修改用户")
  @Path("{user_id}")
  @PUT
  @Produces(MediaType.APPLICATION_JSON)
  public void updateUser(@PathParam("user_id") String userId) {
    System.out.println("修改"+userId);
  }

  // 查
  @ApiOperation(value = "查询单个用户")
  @Path("{user_id}")
  @GET
  @Produces(MediaType.APPLICATION_JSON)
  public UserDTO findUser(@PathParam("user_id") String userId) {
    System.out.println("查询"+userId);
    return null;
  }

  // 批量查询
  @ApiOperation(value = "查询用户列表")
  @GET
  @Produces(MediaType.APPLICATION_JSON)
  public List<UserDTO> findUsers() {
    return null;

  }

}

第三步 在jersey的servlet中配置swagger

    <servlet>
        <servlet-name>Jersey REST Service</servlet-name>
        <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
        <!-- 将SwaggerUI注册到Jersey中 -->
        <!-- 方法1 -->
        <init-param>
            <param-name>jersey.config.server.provider.packages</param-name>
            <param-value>
                huyp.spring.web.api,
                huyp.spring.web.filter,
                io.swagger.jaxrs.listing,
            </param-value>
        </init-param>
        <!-- 方法2 -->
        <init-param>
            <param-name>jersey.config.server.provider.classnames</param-name>
            <param-value>
                org.glassfish.jersey.jackson.JacksonFeature,
                io.swagger.jaxrs.listing.ApiListingResource,
                io.swagger.jaxrs.listing.SwaggerSerializers
            </param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>Jersey REST Service</servlet-name>
        <url-pattern>/rest/*</url-pattern>
    </servlet-mapping>

第四步 配置Swagger的servlet

    <servlet>
        <servlet-name>Swagger Serive</servlet-name>
        <servlet-class>io.swagger.jersey.config.JerseyJaxrsConfig</servlet-class>
        <init-param>
            <param-name>api.version</param-name>
            <param-value>1.5.0</param-value>
        </init-param>
        <init-param>
            <param-name>swagger.api.basepath</param-name>
            <param-value>http://localhost:8080/rest</param-value>
        </init-param>
        <load-on-startup>2</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>Swagger Serive</servlet-name>
        <url-pattern>/api/*</url-pattern>
    </servlet-mapping>

第五步 获取生成swagger生成的json文档，验证结果

在浏览器中访问如下地址，获取程序的json文档

http://[IP]:[端口]/[项目]/swagger.json

如果返回的结果如下图，则说明整合成功！！！

到目前为止，我们已经得到了Swagger规范的json文档，但是看起来很不方便，所以我们使用官方提供的Swagger UI界面来解析这个json文件

解析成功！！！
后续我们会讲解另外一个嵌入式的可视化界面，更加方便！！！

整合Swagger和Spring MVC

Springfox

如果大家在网上搜索swagger整合Spring MVC，一定会发现这个依赖：swagger-springmvc,而Springfox包含了这个依赖并提供了额外的功能。例如springfox 提供了Swagger的UI界面，可以直接在程序中嵌入，无需再部署一套swagger UI服务。
还有更加详细的介绍可以查询Springfox官网。

第一步 在项目中加入springfox依赖

compile group: 'io.springfox', name: 'springfox-swagger2',version:'2.7.0'

第二步 配置springfox参数

官网推荐，使用Java配置的方式，如下：

@Configuration
@EnableSwagger2 //开启Springfox swagger2，Spring Boot中不需要
@EnableWebMvc //开启Spring MVC支持
@ComponentScan(basePackages= {"huyp.spring.web.controller"}) //扫描指定的包
public class SwaggerConfig {

  @Autowired 
  private TypeResolver typeResolver;

  @Bean
  public Docket petApi() {//配置API文档相关信息
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())//API相关描述信息
        .select()//获取ApiSelectorBuilder对api进行各种配置
        .apis(RequestHandlerSelectors.any())//选择暴露的api,默认是any()，即暴露所有api
        .paths(PathSelectors.any())//选择暴露的路径,默认是any()，即暴露所有路径
        .build()//根据提供的api和路径开始构建Docket
        ;
}

private ApiInfo apiInfo() {
    ApiInfo info = new ApiInfo(
      "标题", 
      "描述", 
      "版本", 
      "termsOfServiceUrl", //
      "huyp", // 联系方式
      "Coding.net",//license
      "https://coding.net/u/huyping/p/SpringLearning/git/tree/SpringMVC-Spring-Mybatis");//licenseUrl
    return info;
  }
  }

因为这里没有采用Spring Boot框架，所以需要在Spring的xml配置文件中显示注入bean

<!-- 读取swagger的配置 -->
    <bean class="huyp.spring.web.config.SwaggerConfig" />

第三步 在程序用引入swgger注解

在程序中对应的Controller类中使用swagger注解，这里只展示最常用的几个，更加详细的参数信息可以在官网上查询。

@RestController
@Api(tags="用户")
@RequestMapping("/users")
public class UserController {

  @Autowired
  private UserService userService;

  @ApiOperation("增加用户")
  @RequestMapping(method = RequestMethod.POST, consumes = {MediaType.APPLICATION_JSON_VALUE})
  public void addUser(@RequestBody UserDTO userDTO) {
    userService.addUser(userDTO);
  }

  @ApiOperation("删除用户")
  @DeleteMapping(path = "/{user_id}")
  //相当于 @RequestMapping(path = "/{user_id}", method = RequestMethod.DELETE)
  public void deleteUser(@ApiParam("用户ID")@PathVariable("user_id") String userId) {

  }

  @ApiOperation("更新用户")
  @RequestMapping(path = "/{user_id}", method = RequestMethod.PUT, consumes = {
      MediaType.APPLICATION_JSON_VALUE})
  public void updateUser(@ApiParam("用户ID")@PathVariable("user_id") String userId,
                         @RequestBody UserDTO userDTO) {

  }

  @ApiOperation("查询用户")
  @RequestMapping(path = "/{user_id}", method = RequestMethod.GET, produces = {
      MediaType.APPLICATION_JSON_VALUE})
  public void findUser(@ApiParam("用户ID")@PathVariable("user_id") String userId) {

  }

  @ApiOperation("查询所有的用户")
  @RequestMapping(method = RequestMethod.GET, produces = {MediaType.APPLICATION_JSON_VALUE})
  public void listUser() {

  }

第四步 使用前端页面展示URL

引入springfox提供的前端页面依赖（也可以使用其他的前端页面）

compile group: 'io.springfox', name: 'springfox-swagger-ui',version:'2.7.0'

第五步 配置mvc-servlet对静态资源的处理

<!-- 静态资源处理 -->
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />  
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" />

第六步 访问swagger主页验证结果

在浏览器中访问spring-fox提供的UI界面的首页

http://[IP]:[端口]/[项目名]/swagger-ui.html

如果出现如下图所示的界面，则表明Swagger和Spring MVC整合成功！！！

踩过的坑

1、因为一直希望跟紧时代的脚步，所以在程序中全部到采用了最新的依赖，导致出现了缺少依赖的问题，如果发现出现jackson找不到类的情况，可能是缺少如下依赖。

//jackson依赖,用来将对象转化为json（新版本的io.springfox需要的版本很高）
compile group: 'com.fasterxml.jackson.core', name: 'jackson-databind',version:'2.9.3'

2、如果是Spring MVC相关的错误，这篇文章不会介绍，但是之后会持续更新Sping MVC相关文章，敬请期待！！！