spring boot+swagger 生成Restful风格API

这段时间项目告一段落，开始回过头来补充完善一些资料，包括数据库设计和API文档。之前都是手写文档，须要手动去调整格式，接口有更新还得改文档，测试也要单独写代码。

有了swagger这些工做所有省掉了，只须要在写接口的时候多加点注解就搞定。

废话很少说直接进入主题，先说下步骤：

一、引入maven依赖

二、利用springboot的config配置方式进行配置

三、在接口上加入swagger注解

四、启动服务进行查看和测试

一、引入maven依赖

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>org.json</groupId>
            <artifactId>json</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.restdocs</groupId>
            <artifactId>spring-restdocs-mockmvc</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-staticdocs</artifactId>
            <version>2.6.1</version>
        </dependency>

        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>druid</artifactId>
            <version>1.0.18</version>
        </dependency>

二、利用springboot的config配置方式进行配置

package com.mymall.crawlerTaskCenter.config;

import java.util.ArrayList;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RequestMethod;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
 
@Configuration
@ComponentScan
@EnableSwagger2
public class SwaggerConfig {
 
    @Bean
    public Docket petApi() {
         
        //自定义异常信息
         ArrayList<ResponseMessage> responseMessages = new ArrayList<ResponseMessage>() {{
                add(new ResponseMessageBuilder().code(200).message("成功").build());
                add(new ResponseMessageBuilder().code(400).message("请求参数错误").responseModel(new ModelRef("Error")).build());
                add(new ResponseMessageBuilder().code(401).message("权限认证失败").responseModel(new ModelRef("Error")).build());
                add(new ResponseMessageBuilder().code(403).message("请求资源不可用").responseModel(new ModelRef("Error")).build());
                add(new ResponseMessageBuilder().code(404).message("请求资源不存在").responseModel(new ModelRef("Error")).build());
                add(new ResponseMessageBuilder().code(409).message("请求资源冲突").responseModel(new ModelRef("Error")).build());
                add(new ResponseMessageBuilder().code(415).message("请求格式错误").responseModel(new ModelRef("Error")).build());
                add(new ResponseMessageBuilder().code(423).message("请求资源被锁定").responseModel(new ModelRef("Error")).build());
                add(new ResponseMessageBuilder().code(500).message("服务器内部错误").responseModel(new ModelRef("Error")).build());
                add(new ResponseMessageBuilder().code(501).message("请求方法不存在").responseModel(new ModelRef("Error")).build());
                add(new ResponseMessageBuilder().code(503).message("服务暂时不可用").responseModel(new ModelRef("Error")).build());
                add(new ResponseMessageBuilder().code(-1).message("未知异常").responseModel(new ModelRef("Error")).build());
            }};
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mymall.crawlerTaskCenter.web.rest"))//扫描的API包
                .paths(PathSelectors.any())
                .build()
                .useDefaultResponseMessages(false)
                .globalResponseMessage(RequestMethod.GET, responseMessages)
                .globalResponseMessage(RequestMethod.POST, responseMessages)
                .globalResponseMessage(RequestMethod.PUT, responseMessages)
                .globalResponseMessage(RequestMethod.DELETE, responseMessages);
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("MyMall 爬虫任务中心Restful APIs")
                .description("author:彭小康  2017年8月28日")
                .version("2.0").build();
    }
 
}

三、在接口上加入swagger注解

package com.mymall.crawlerTaskCenter.web.rest;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

import java.util.List;

import javax.servlet.http.HttpServletRequest;

import org.apache.commons.lang.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import com.alibaba.fastjson.JSON;
import com.mymall.crawlerTaskCenter.domain.CrawlerJob;
import com.mymall.crawlerTaskCenter.log.LogsManager;
import com.mymall.crawlerTaskCenter.service.CrawlerJobService;

@RestController
@RequestMapping(value = "/job")
@Api(value = "爬虫任务管理", description = "爬虫任务管理API", tags = "CrawlerJobApi", consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)
public class CrawlerJobController {
	private static org.apache.logging.log4j.Logger logger = LogsManager.getLocalLogger(CrawlerJobController.class.getName(),"job");
	@Autowired
	CrawlerJobService crawlerJobService;
	
	/**
	 * 获取最新任务
	 * @return
	 */
	@RequestMapping(value = "/getJobs", method = RequestMethod.GET)
	@ApiOperation(value = "getJobs 获取最新任务", notes = "requires job number")
	public List<CrawlerJob> getJobs(
			@ApiParam(required = false, name = "jobNum", value = "任务数量，若是不传该参数则默认给20条，若是任务中心少于20条则所有返回") Integer jobNum,
			@ApiParam(required = false, name = "jobType", value = "任务类型：platform-平台，allNetList-全网列表任务") String jobType,
			@ApiParam(required = false, name = "key", value = "任务key") String key 
			,HttpServletRequest request) {
		String ip = request.getHeader("X-Real-IP");
		if (StringUtils.isBlank(ip) ||"unknown".equalsIgnoreCase(ip)) {
			ip=request.getRemoteAddr();
		}
		logger.info(ip+"领取了"+jobNum+"条任务");
		return crawlerJobService.getJobs(jobNum, jobType,ip,key);
	}
	
	/**
	 * 提交任务
	 * @return
	 */
	@RequestMapping(value = "/submitJob", method = RequestMethod.POST)
	@ApiOperation(value = "submitJob 提交任务", notes = "根据id提交任务")
	public  boolean submitJob(@ApiParam(required = true, name = "job", value = "任务id") String job,HttpServletRequest request) {
		String ip = request.getHeader("X-Real-IP"); request.getParameter("id");
		if (StringUtils.isBlank(ip) ||"unknown".equalsIgnoreCase(ip)) {
			ip=request.getRemoteAddr();
		}
		CrawlerJob cjob=JSON.parseObject(job,CrawlerJob.class);
		logger.info(ip+"提交了任务，id为:"+cjob.getId());
		return crawlerJobService.submitJob(cjob);
	}
	
	/**
	 * 建立任务
	 * @return
	 */
	@RequestMapping(value = "/createJob", method = RequestMethod.POST)
	@ApiOperation(value = "createJob 建立任务", notes = "根据json建立任务")
	public  boolean createJob(@ApiParam(required = true, name = "taskJsonStr", value = "任务json字符串") String taskJsonStr){
		return crawlerJobService.createJob(taskJsonStr);
	}
	
	/**
	 * 更新任务
	 * @return
	 */
	@RequestMapping(value = "/updateJob", method = RequestMethod.POST)
	@ApiOperation(value = "updateJob 更新任务", notes = "requires job")
	public boolean updateJob(
			@ApiParam(required = false, name = "job", value = "须要更新任务的json格式数据") String job
			,HttpServletRequest request) {
		String ip = request.getHeader("X-Real-IP");
		if (StringUtils.isBlank(ip) ||"unknown".equalsIgnoreCase(ip)) {
			ip=request.getRemoteAddr();
		}
		logger.info(ip+"更新任务："+job);
		return crawlerJobService.updateJob(job);
	}
}

四、启动服务进行查看和测试

根据本身服务时间发布的地址进行访问，个人地址是：http://localhost:8082/swagger-ui.html

展开某个接口，提供了测试方法，填写对应参数，点击try it按钮便可看到运行结果