环境：Spring Boot，Swagger，gradle，Postman，newman，jenkins
SpringBoot环境搭建。
Swagger简介
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。

image.png

一、SpringBoot集成Swagger

1.build.gradle增加swagger相关jar包，maven项目同理。

image.png

2.增加SwaggerConfig配置文件。

前两步完成，访问http://localhost:8080/demoService/swagger-ui.html#/即可看见swagger的api页面了。下面几个步骤是为了解决一些配置问题，没有以下几种问题可以不用配置。

package com.example.demo;

import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;


@Configuration
@EnableSwagger2
@ConditionalOnExpression("${swagger.enable:true}")
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        ParameterBuilder sessionIdPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        sessionIdPar.name("SESSIONID").description("用户 sessionid")
                .modelRef(new ModelRef("string")).parameterType("header")
                .required(true).build();
        pars.add(sessionIdPar.build());    //根据每个方法名也知道当前方法在设置什么参数
        return new Docket(DocumentationType.SWAGGER_2)
                .globalOperationParameters(pars)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restfun风格")
                .version("1.0")
                .build();
    }

}

image.png

3.生产环境不部署问题

解决生产环境不部署问题，application.yml增加配置信息。SwaggerConfig增加注解信息，完整配置文件信息在下方。
swagger.enable

image.png

4. 配置用户名密码

配置用户名密码访问swagger需要增加spring-boot-starter-security。

compile('org.springframework.boot:spring-boot-starter-security')

增加用户名密码登录限制。application.yml增加配置信息。

security:
  basic:
    path: /swagger-ui.html
    enabled: true
  user:
    name: lifeccp
    password: lifeccp

application.yml完整配置文件

#配置服务信息
#配置服务信息
server:
  address: localhost
  context-path: /demoService
  port: 8080
spring:
  profiles.active: dev

---
spring:
  profiles: dev
swagger:
    enable: false
security:
  basic:
    path: /swagger-ui.html
    enabled: true
  user:
    name: lifeccp
    password: lifeccp
---

---
spring:
  profiles: test
swagger:
    enable: true
security:
  basic:
    path: /swagger-ui.html
    enabled: true
  user:
    name: lifeccp
    password: lifeccp
---

---
spring:
  profiles: prod
swagger:
    enable: true
security:
  basic:
    path: /swagger-ui.html
    enabled: true
  user:
    name: lifeccp
    password: lifeccp
---
---

5.拦截器拦截swagger url问题。

为了防止自定义拦截器拦截swagger地址。需要增加拦截器配置。

package com.example.demo;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.util.StringUtils;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import org.springframework.web.servlet.handler.HandlerInterceptorAdapter;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

@Configuration
@Profile({"dev","prod", "test"})
public class ServletConfig extends WebMvcConfigurationSupport {
    private static final Logger LOG = LoggerFactory.getLogger(ServletConfig.class);
    private static final String[] EXCLUE_PATH = {"/swagger-resources/**", "/webjars/**", "/swagger-ui.html/**"};

    @Override
    protected void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new HandlerInterceptorAdapter() {

            @Override
            public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
                String sessionid = request.getHeader("SESSIONID");

                if (StringUtils.isEmpty(sessionid)) {
                    response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
                    return false;
                }

                LOG.info("got sessionid : {}", sessionid);
                return true;
            }

            @Override
            public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {

            }
        }).addPathPatterns("/**").excludePathPatterns(EXCLUE_PATH);
    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

二、swagger注解

常用的注解在这里列举一下，详细的需求还是要去看文档。

//用在类上，说明该类的作用。
@Api(tags = "会诊记录相关api")
//用在方法上，给API增加方法说明。
@ApiOperation(value="Get测试", notes="Get类型测试")
//用来注解来给方法入参增加说明。
@ApiImplicitParam(name = "id", value = "会诊id", required = true, dataType = "int", paramType = "path")
//用在方法上包含一组参数说明。
@ApiImplicitParams({
            @ApiImplicitParam(paramType="path", name = "id", value = "记录id", required = true, dataType = "Integer"),
            @ApiImplicitParam(paramType="query", name = "name", value = "记录名称", required = true, dataType = "String"),
    })
//用在方法上设置reponse数据格式
@ApiResponses({@ApiResponse(code = 200,response = UserInfoDTO.class, message = "success")})

//用在对象上
@ApiModel(value = "用户对象")
@ApiModelProperty(value = "id")

@ApiModel(value = "用户对象")
public class UserInfoDTO {
    @ApiModelProperty(value = "id")
    private int id ;
    @ApiModelProperty(value = "用户姓名")
    private String name ;
    @ApiModelProperty(value = "昵称")
    private String nickName ;
    set() ...
    get() ...
}

API完整代码

@RestController
@EnableAutoConfiguration
@Api(tags = "Demo相关api")
public class SampleController {

    @Value("${server.address}")
    private String address ;

    @Value("${server.port}")
    private String port ;

    @RequestMapping(value = "/sample/{id}",method = RequestMethod.GET)
    @ApiOperation(value="Get测试", notes="Get类型测试")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType="path", name = "id", value = "记录id", required = true, dataType = "Integer"),
            @ApiImplicitParam(paramType="query", name = "name", value = "记录名称", required = true, dataType = "String"),
    })
    String home(@PathVariable("id")String id,@RequestParam("name")String name){
        try{
            if(Integer.parseInt(id) > 10){
                return "number" ;
            }
        }catch (Exception e){
            return "error" ;
        }
        return "helloworld" ;
    }

    @RequestMapping(value = "/sample",method = RequestMethod.POST)
    @ResponseBody
    @ApiOperation(value="POST测试", notes="POST类型测试")
    Object testPost(@RequestBody UserInfoDTO userInfoDTO){
        return userInfoDTO ;
    }
}

Demo：https://github.com/xinzhongyi/SpringBootExample/tree/master/swagger-demo

三、Swagger一键导入Postman

Postman是一款http请求测试软件，不知道的同学可以自己去百度并下载使用下。
Postman可以导入Swagger的api请求，这样就不用一个一个去录入了，录入到Postman后可以利用Postman的自动化测试工具，后续还可以使用jenkins自动化继承Postman接口测试。

image.png

image.png

上图的地址填入下图中红框圈住的地址即可。

image.png

image.png

四、Postman 测试

以下只是使用了一个最简单的测试，Postman还有很多其他功能，具体可以参考官方文档。
官方文档地址：https://learning.getpostman.com/docs/postman/scripts/test_examples/

创建测试api，我是利用本机地址测试。测试api如下。
http://localhost:8080/demoService/sample/{{id}}
Tests测试用例如下
tests["result is"] = responseBody === data.result
测试数据如下，id参数可以从文件中获取，这样就不用每次手动去改。

[{
  "id": "1",
  "result": "helloworld"
}, {
  "id": "post",
  "result": "error"
}, {
  "id": "20",
  "result": "number"
}]

上面都是为测试准备的数据，下面开始进行Postman测试。

创建测试API

打开测试用例界面

选择测试数据文件

查看测试数据信息

测试结束

五、newman集成postman测试

windows安装newman,首先你得现有node环境跟npm命令。
npm install -g newman

newman

newman run test.postman_collection -d data.json

执行测试计划

newman run test.postman_collection -d data.json -r html --reporter-html-export ./testReport.html
测试并且声称测试报告

测试报告

六、jenkins集成postman测试

未测试过jenkins集成测试，jenkins也是去执行newman命令执行测试。

jenkins集成