Stringboot2.0集成Swagger2项目实战

Swagger是什么

• 前后端分离开发模式中，api文档是最好的沟通方式。
• 特点
  • Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
  • 及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)
  • 规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)
  • 一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)
  • 可测性 (直接在接口文档上进行测试，以方便理解业务)
    说白了就是如果你不想每天花1小时写文档，那么Swagger是帮你实现接口文档的得力干将

Stringboot集成 Swagger

配置信息

pom.xml文件引入jar包

		<!--如果包不冲突可以不用使用此包-->
		<dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>28.0-jre</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

Swagger2 配置类

@Configuration
public class Swagger2 {

    @Value("${swagger.show}")
    private boolean swaggerShow;

    @Bean
    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .enable(swaggerShow)// 设置正式环境不显示Swagger2
        .select()
//        .apis(RequestHandlerSelectors.basePackage("org.zsdy")) // 单个扫描路径
        .apis( // 配置多个扫描路径
            Predicates.or(
            RequestHandlerSelectors.basePackage("org.admin.controller"),
            RequestHandlerSelectors.basePackage("org.ext.admin.controller")
            )
        )
        .paths(PathSelectors.any())
        .build();
    }

    private ApiInfo apiInfo() {
        // name：作者，url：通常项目地址，email：邮箱
        Contact contact=new Contact("lsw",
        "https://blog.csdn.net/Extraordinarylife"," ");
        return new ApiInfoBuilder()
        .title("数据中心接口文档")//标题
        .description("数据中心相关接口文档")// 描述
        .contact(contact)
        .version("1.0")//版本
        .build();
    }
}

启动类增加注解
@EnableSwagger2

Swagger2常用注解

• @Api()用于类；
  表示标识这个类是swagger的资源
• @ApiOperation()用于方法；
  表示一个http请求的操作
• @ApiParam()用于方法，参数，字段说明；
  表示对参数的添加元数据（说明或是否必填等）
• @ApiModel()用于类
  表示对类进行说明，用于参数用实体类接收
• @ApiModelProperty()用于方法，字段
  表示对model属性的说明或者数据操作更改
• @ApiIgnore()用于类，方法，方法参数
  表示这个方法或者类被忽略
• @ApiImplicitParam() 用于方法
  表示单独的请求参数
• @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

项目实际应用

Controller简单示例

@RestController
@RequestMapping("mapping")
@Slf4j
@Api(tags = "图谱接口")
public class MappingController extends CommonController {

    @Autowired
    MappingService mappingService;

    @ApiOperation(value="图谱分类新增")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "model", value = "图谱分类实体", dataType = "model")
    })
    @ApiResponses({
        @ApiResponse(code = 200,message = "OK",response = MappingDTO.class),
    })
    @RequestMapping(value="save", method=RequestMethod.POST)
    public Result save (@ModelAttribute Mapping model) {
        mappingService.save(model);
        return ResultUtils.wrapSuccess(model);
    }
    @ApiOperation(value="图谱分类修改")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "model", value = "图谱分类实体", dataType = "model")
    })
    @ApiResponses({
        @ApiResponse(code = 200,message = "OK",response = MappingDTO.class),
    })
    @RequestMapping(value="update", method=RequestMethod.PUT)
    public Result update (@ModelAttribute Mapping model) {
        mappingService.update(model);
        return ResultUtils.wrapSuccess(model);
    }
    @ApiOperation(value="图谱分类删除")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "图谱分类ID", required = true, dataType = "Integer")
    })
    @RequestMapping(value="/delete/{id}", method=RequestMethod.DELETE)
    public Result delete (@PathVariable Integer id) {
        mappingService.deleteById(id);
        return ResultUtils.wrapSuccess();
    }
    @ApiOperation(value="查看图谱分类")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "图谱分类ID", required = true, dataType = "Integer")
    })
    @ApiResponses({
        @ApiResponse(code = 200,message = "OK",response = Mapping.class),
    })
    @RequestMapping(value="/detail/{id}", method=RequestMethod.GET)
    public Result detail (@PathVariable Integer id) {
        Mapping single = mappingService.findById(id);
        return ResultUtils.wrapSuccess(single);
    }
}

接参实体类
@ApiModelProperty中有一些特定参数可以多查看下源码定制分析下

@Data
public class Mapping {

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

    @ApiModelProperty(value="父id", example = "0")
    private Integer parentId;

    @ApiModelProperty(value = "排序字段", example = "0")
    private Integer seq;

    @ApiModelProperty(value = "名称", example = "图谱分类")
    private String name;

    @ApiModelProperty(value = "创建时间",hidden = true)
    private Date createTime;

    @ApiModelProperty(value = "更新时间",hidden = true)
    private Date updateTime;

}

响应实体类
列表中元素类型如果是当前bean childen内则不显示描述

@Data
@ApiModel
public class MappingDTO {
    @ApiModelProperty(value = "主键")
    private Integer id;

    @ApiModelProperty(value = "父id")
    private Integer parentId;

    @ApiModelProperty(value = "排序字段")
    private Integer seq;

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

    @ApiModelProperty(value = "父分类名称")
    private String parentName;

    @ApiModelProperty(value = "子集同当前字段")
    private List<MappingDTO> childen;
}