Swagger-UI入门教程

目录

1.添加依赖

2.添加配置

3.代码演示

4.文档效果

5.注解说明

---

1.添加依赖

<!--Swagger-UI API文档生产工具-->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.7.0</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.7.0</version>
</dependency>

2.添加配置

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包下controller生成API文档
                .apis(RequestHandlerSelectors.basePackage("com.ak.mall.controller"))
                //为有@Api注解的Controller生成API文档
//                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //为有@ApiOperation注解的方法生成API文档
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SwaggerUI演示")
                .description("ak-mall")
                .contact("ak")
                .version("1.0")
                .build();
    }

}

3.代码演示

@Api(tags = "TestSwaggerController", description = "测试Swagger控制器")
@RestController
@RequestMapping("/test/swagger")
public class TestSwaggerController {


    @ApiOperation(value = "测试查询接口")
    @RequestMapping(value = "query",method = RequestMethod.POST)
    public QueryOutVO query(@Validated @RequestBody QueryInVO queryInVO) {
        QueryOutVO queryOutVO = new QueryOutVO();
        BeanUtils.copyProperties(queryInVO, queryOutVO);
        return queryOutVO;
    }

}

@Data
@ApiModel(value = "查询入参VO")
public class QueryInVO {

    @NotBlank(message = "id 为空")
    @ApiModelProperty(value = "主键id")
    private String id;

    @NotBlank(message = "name 为空")
    @ApiModelProperty(value = "名称")
    @JsonProperty(value = "nameA")
    private String name;
}

@Data
@ApiModel(value = "查询返参VO")
public class QueryOutVO {

    @ApiModelProperty(value = "主键id")
    private String id;

    @ApiModelProperty(value = "名称")
    @JsonProperty(value = "nameB")
    private String name;
}

4.文档效果

        http://localhost:8080/swagger-ui.html

5.注解说明

• @Api：用于修饰Controller类，生成Controller相关文档信息
• @ApiOperation：用于修饰Controller类中的方法，生成接口方法相关文档信息
• @ApiParam：用于修饰接口中的参数，生成接口参数相关文档信息
• @ApiModel：用于修饰实体类，生成实体类相关文档信息
• @ApiModelProperty：用于修饰实体类的属性，当实体类是请求参数或返回结果时，直接生成相关文档信息
• @JsonProperty：用于修饰实体类的属性别名，当实体类是请求参数或返回结果时，直接生成相关文档信息