環(huán)境：Spring Boot，Swagger，gradle，Postman，newman，jenkins
SpringBoot環(huán)境搭建。
Swagger簡介
Swagger 是一款RESTFUL接口的文檔在線自動(dòng)生成+功能測試功能軟件。

image.png

一、SpringBoot集成Swagger

1.build.gradle增加swagger相關(guān)jar包，maven項(xiàng)目同理。

image.png

2.增加SwaggerConfig配置文件。

前兩步完成，訪問http://localhost:8080/demoService/swagger-ui.html#/即可看見swagger的api頁面了。下面幾個(gè)步驟是為了解決一些配置問題，沒有以下幾種問題可以不用配置。

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());    //根據(jù)每個(gè)方法名也知道當(dāng)前方法在設(shè)置什么參數(shù)
        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構(gòu)建api文檔")
                .description("簡單優(yōu)雅的restfun風(fēng)格")
                .version("1.0")
                .build();
    }

}

image.png

3.生產(chǎn)環(huán)境不部署問題

解決生產(chǎn)環(huán)境不部署問題，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完整配置文件

#配置服務(wù)信息
#配置服務(wù)信息
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注解

常用的注解在這里列舉一下，詳細(xì)的需求還是要去看文檔。

//用在類上，說明該類的作用。
@Api(tags = "會(huì)診記錄相關(guān)api")
//用在方法上，給API增加方法說明。
@ApiOperation(value="Get測試", notes="Get類型測試")
//用來注解來給方法入?yún)⒃黾诱f明。
@ApiImplicitParam(name = "id", value = "會(huì)診id", required = true, dataType = "int", paramType = "path")
//用在方法上包含一組參數(shù)說明。
@ApiImplicitParams({
            @ApiImplicitParam(paramType="path", name = "id", value = "記錄id", required = true, dataType = "Integer"),
            @ApiImplicitParam(paramType="query", name = "name", value = "記錄名稱", required = true, dataType = "String"),
    })
//用在方法上設(shè)置reponse數(shù)據(jù)格式
@ApiResponses({@ApiResponse(code = 200,response = UserInfoDTO.class, message = "success")})

//用在對(duì)象上
@ApiModel(value = "用戶對(duì)象")
@ApiModelProperty(value = "id")

@ApiModel(value = "用戶對(duì)象")
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相關(guān)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一鍵導(dǎo)入Postman

Postman是一款http請(qǐng)求測試軟件，不知道的同學(xué)可以自己去百度并下載使用下。
Postman可以導(dǎo)入Swagger的api請(qǐng)求，這樣就不用一個(gè)一個(gè)去錄入了，錄入到Postman后可以利用Postman的自動(dòng)化測試工具，后續(xù)還可以使用jenkins自動(dòng)化繼承Postman接口測試。

image.png

image.png

上圖的地址填入下圖中紅框圈住的地址即可。

image.png

image.png

四、Postman 測試

以下只是使用了一個(gè)最簡單的測試，Postman還有很多其他功能，具體可以參考官方文檔。
官方文檔地址：https://learning.getpostman.com/docs/postman/scripts/test_examples/

創(chuàng)建測試api，我是利用本機(jī)地址測試。測試api如下。
http://localhost:8080/demoService/sample/{{id}}
Tests測試用例如下
tests["result is"] = responseBody === data.result
測試數(shù)據(jù)如下，id參數(shù)可以從文件中獲取，這樣就不用每次手動(dòng)去改。

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

上面都是為測試準(zhǔn)備的數(shù)據(jù)，下面開始進(jìn)行Postman測試。

創(chuàng)建測試API

打開測試用例界面

選擇測試數(shù)據(jù)文件

查看測試數(shù)據(jù)信息

測試結(jié)束

五、newman集成postman測試

windows安裝newman,首先你得現(xiàn)有node環(huán)境跟npm命令。
npm install -g newman

newman

newman run test.postman_collection -d data.json

執(zhí)行測試計(jì)劃

newman run test.postman_collection -d data.json -r html --reporter-html-export ./testReport.html
測試并且聲稱測試報(bào)告

測試報(bào)告

六、jenkins集成postman測試

未測試過jenkins集成測試，jenkins也是去執(zhí)行newman命令執(zhí)行測試。

jenkins集成