接口文档神器Swagger教程，一看就会

需求：

在开发过程中，经常需要前后端一起工作，那工作核心就是交互的接口文档。但是在动态的开发过程中，请求、返回报文、接口等也是动态增减的，所以使用Swagger可以直接时时的查看到最新的接口文档，还能简单的调用接口。

1、引入jar包

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
    <version>2.6.0version>
dependency>
<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
    <version>2.6.0version>
dependency>

2、swagger的配置文档

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${env}")
    private String env;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(!StringUtils.equals(env, "production"))//非生产环境开启文档
                .groupName("test")//Docket的组名，可以创建多个Docket
                .apiInfo(apiInfo())//swagger基本信息
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))//生成接口文档,使用过ApiOperation注解的
                //.apis(RequestHandlerSelectors.basePackage("com.qsm.xx"))//生成接口文档,使用包名
                .paths(!StringUtils.equals(env, "production") ? PathSelectors.any() : PathSelectors.none()).build();//生产环境不生产文档
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxx学习计划")
                .description("xxx学习计划是一项针对中小学生的扩展教育方式")
                .termsOfServiceUrl("")
                .version("1.0")
                .contact(new Contact("qsm", "", "[email protected]")).build();
    }
}

3、基本注解

• @Api()用于类； 表示标识这个类是swagger的资源

• @ApiOperation()用于方法； 表示一个http请求的操作

• @ApiParam()用于方法，参数，字段说明；

• @ApiImplicitParam() 用于方法 表示单独的请求参数

• @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

• @ApiResponse：返回参数的说明

• @ApiResponses：方法返回对象的说明，包含多个 @ApiResponse

• @ApiModel() 用于实体类

• @ApiModelProperty() 用于实体类字段

• @ApiIgnore() 用于类，方法，方法参数，表示这个方法或者类被忽略

4、java代码演示

@RestController
@RequestMapping("/insure")
@Slf4j
@Api(tags = "保单相关的接口")
public class InsureApiController {

    //用于一般get请求
    @ApiOperation("获取用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户Id")
    })
    @ApiResponses({
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 400, message = "请求参数没填好"),
            @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
    })
    @GetMapping("/list")
    public ReturnResult<String> list(@RequestParam String userId) {
        return null;
    }

    //用于一般post请求
    @PostMapping("/policyList")
    @ApiOperation(value = "保单列表查询", httpMethod = "POST")
    public ReturnResult<List<SspPolicyDTO>> queryPolicyList(@RequestBody SspPolicyListQueryReq queryParams) throws Exception {
        return null;
    }
}

//一般Controller上请求和返回对象上加@ApiModel和 @ApiModelProperty
@Data
@ApiModel(value = "com.qsm.xx.SspPolicyDTO", description = "保单DTO")
public class SspPolicyDTO {

    @ApiModelProperty(value = "公司名", name = "companyName")
    private String companyName;

    @ApiModelProperty(value = "健康告知", name = "remark")
    private String remark;
}

5、swagger在线地址

本地启动
项目没有配置context-path项目路径时为：
http://localhost:8080/swagger-ui.html
项目配置context-path项目路径/qsm时为：
http://localhost:8080/qsm/swagger-ui.html

其他环境

http://${ip}:{port}/swagger-ui.html

http://${ip}:{port}/xxx/swagger-ui.html

【正在去BAT的路上修行】