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

文章目录

        • 需求:
          • 1、引入jar包
          • 2、swagger的配置文档
          • 3、基本注解
          • 4、java代码演示
          • 5、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的路上修行】

你可能感兴趣的:(工具)