一、背景介绍

1.1.项目简介
1.2.code repository
1.3.演示项目

二、开发准备

2.1.环境准备
2.2.项目搭建

2.2.1.jar仓库
2.2.2.相关依赖
2.2.3.编写配置文件
2.2.4.与swagger-ui集成
2.6.5.Controller配置
2.2.6.启动中间件
2.2.7.需求定制

三、学习感想

一、背景介绍

1.1.项目简介

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

1.2.code repository

1.3.演示项目

官方：https://github.com/adrianbk/swagger-springmvc-demo
民间：https://github.com/qq291462491/bugkillers

二、开发准备

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") 需要扫描的包路径

示例：

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="http://127.0.0.1:9081/api" "="" style="color: rgb(59, 115, 175); text-decoration: none; border-radius: 0px !important; border: 0px !important; bottom: auto !important; float: none !important; height: auto !important; left: auto !important; margin: 0px
 !important; outline: 0px !important; overflow: visible !important; padding: 0px !important; position: static !important; right: auto !important; top: auto !important; vertical-align: baseline !important; width: auto !important; box-sizing: content-box !important;
 min-height: inherit !important; background: none !important;">http://127.0.0.1:9081/api",

              "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的配置文件中共配置：（不推荐）

<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

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

<!--
 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：

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配置好的话就可以启动看效果了。

访问本机：http://127.0.0.1:9081/api

远程示例：http://115.29.170.213/api

2.2.7.需求定制

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

三、学习感想

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

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

Swagger框架学习分享