swagger API 摆脱手写API的烦恼(ssm + swagger)

先说一下为什么会发现它把，来公司一个月了，之前没有做过app服务器端这种纯接口开发工作，从最初的什么都没有到最后项目对接，做一下自己的总结把。刚开始，想好需要什么功能就直接上手写，到用markdown写好接口规划，再到用百度脑图规划好都是些什么功能，最后按计划实现各个接口，完了之后手写API文档，最后交付iOS去完成对接。这也算是一个缓慢的成长吧，最苦恼与手写API文档，先写好一个，后面直接复制粘贴，改请求方式、参数、响应结果等一些列的，写了几个就感觉好烦，果然程序员都很懒，开始想办法怎么省事，从最初找一些写API的网站到找一些开源网站，发现并不是很好用，甚至萌生出一个自己写一个实用工具的想法，最后终于在一个开源项目中发现有使用swagger来自动生成API，大喜过望赶紧上手，在这给大家分享一下，也做一下备忘。

---

上面都是废话，下面开始正文

背景结构：

<spring.version>4.3.4.RELEASE</spring.version>
<swagger.version>2.4.0</swagger.version>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

添加swagger的配置：（通过注解实现配置）

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.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;


import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/* 
 * Restful API 访问路径: 
 * http://IP:port/{context-path}/swagger-ui.html 
 * eg:http://localhost:8080/deepai/swagger-ui.html 
 */
@EnableWebMvc
@EnableSwagger2
@ComponentScan(basePackages = {"cn.deepai.web"})
@Configuration
public class SwaggerConfig extends WebMvcConfigurationSupport{

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.deepai.web"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("深镜智能 - API")
                .termsOfServiceUrl("http://blog.csdn.net/dark_guo?viewmode=contents")
                .contact("idark")
                .version("1.0")
                .build();
    }
}  

到这里，swagger的配置就完成了，后面就是在控制器里去添加API的注解了。

事例代码：

/**
 *
 * 测试用 api
 *
 * Created by guoyakui on 2017/5/24.
 */
@Api(description = "测试使用的 API ")
@Controller
public class IndexController {

    @Autowired
    private UserService userService;

    @ApiOperation(value = "进入index页面", notes = "进入index页面", httpMethod = "GET")
    @RequestMapping(value = "/", method = RequestMethod.GET)
    @ResponseBody
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "String"),
            @ApiImplicitParam(name = "userName", value = "用户名", required = true, dataType = "String"),
            @ApiImplicitParam(name = "sex", value = "性别", required = true, dataType = "String"),
            @ApiImplicitParam(name = "age", value = "年龄", required = true, dataType = "int")})
    public Map addInfo(HttpServletRequest request){

        //测试 spring session
        request.getSession().setAttribute("id", request.getParameter("id"));
        request.getSession().setAttribute("userName", request.getParameter("userName"));
        request.getSession().setAttribute("age", request.getParameter("age"));
        request.getSession().setAttribute("sex", request.getParameter("sex"));

        Map map = new HashMap();
        map.put("code", true);
        map.put("message", "添加成功");

        return map;
    }

    @ApiOperation(value = "获取数据")
    @RequestMapping(value = "/getsession", method = RequestMethod.GET)
    @ResponseBody
    public Map index2(HttpServletRequest request){

        Map map = new HashMap();
        map.put("id",request.getSession().getAttribute("id"));
        map.put("userName",request.getSession().getAttribute("userName"));
        map.put("age",request.getSession().getAttribute("age"));
        map.put("sex",request.getSession().getAttribute("sex"));

        map.put("sessionId", request.getSession().getId());

        return map;
    }
}

效果展示：