Swagger

其它

发布时间 : 2022-10-05 00:51

字数:1k 阅读 :

Swagger2

Swagger2

简介

Swagger是一套基于 OpenAPI 规范构建的开源工具，可以帮助我们设计，构建，记录以及使用Rest API

为什么使用

当今大部分公司都采用前后端分离的模式来开发项目，前端和后端的工作由不同的工程师来完成，这种开发模式下，维持一份及时更新且完善的Rest API 文档将会极大的提高我们的工作效率

传统意义上的文档都是后端开发人员手动编写的，这种方式很难保证文档的及时性，这种文档久而久之也会失去参考意义，反而还会增加沟通成本，而Swagger给我们提供了一个全新的API文档维护方式

优点：

代码变，文档变，只需要少量的注解，Swagger就可以根据代码自动生成API文档，保证了文档的及时性
跨语言性，Swagger支持40多种语言
Swagger UI呈现出来的是一份可交互式的API文档，我们可以直接在文档中尝试API的调用，省略了复杂的参数调用过程

快速入门

引入依赖

<!-- swagger2 -->
<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>

启用Swagger2

在启动类上或者配置类加 @EnableSwagger2 注解

访问swagger文档： http://localhost:8080/swagger-ui.html

注意： 其中的localhost:8080在项目中都要改为真实域名+端口号

具体配置

Controller配置

@Api注解

属性：

tags 设置标签
description 设置描述信息

@RestController
@RequestMapping("/comment")
@Api(tags = "评论",description = "评论相关接口")
public class CommentController {
}

接口配置

@ApiOperation 接口描述

@GetMapping("/linkCommentList")
@ApiOperation(value = "友链评论列表",notes = "获取一页友链评论信息")
public ResponseResult linkCommentList(Integer pageNum,Integer pageSize){
    return commentService.linkCommentList(pageNum,pageSize);
}

@ApiImplicitParam ** 用于描述接口的非对象参数，但是一个接口可能有多个参数，所以一般与@ApiImplicitParams **组合使用

@GetMapping("/linkCommentList")
@ApiOperation(value = "友链评论列表",notes = "获取一页友链评论信息")
@ApiImplicitParams({
        @ApiImplicitParam(name = "pageNum",value = "页号"),
        @ApiImplicitParam(name = "pageSize",value = "每页大小")
})
public ResponseResult linkCommentList(Integer pageNum,Integer pageSize){
    return commentService.linkCommentList(pageNum,pageSize);
}

实体类配置

@ApiModel 用于描述实体类

@ApiModelProperty 用于描述实体的属性

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(description = "添加评论Dto")
public class AddCommentDto {

    private Long id;
    //评论类型（0代表文章评论，1代表友链评论）
    @ApiModelProperty(notes = "评论类型（0代表文章评论，1代表友链评论）")
    private String type;
    //文章id
    @ApiModelProperty(notes = "文章id")
    private Long articleId;
    //...   
}

在实际开发中，我们一般不会用与数据库建立表关系的对象来接收前端传输的数据，接收参数和实际数据库中的表字段也不一定完全相同

这样子在使用Swagger注解的时候也会和不同的方法需要接收的参数产生耦合

因此我们一般会封装一层DTO对象（Data Transaction Object数据传输对象，数据事务对象）

修改表现层参数

@PostMapping
public ResponseResult comment(@RequestBody AddCommentDto addCommentDto){
    Comment comment = BeanCopyUtils.copyBean(addCommentDto, Comment.class);
    return commentService.comment(comment);
}

这里接收到的CommentDto对象再拷贝成Comment对象即可

文档信息配置类

加上**@Configuration注解**

需要返回一个Docket对象，加上**@bean注解**

使用了构造器模式创建了Docket和apiInfo

配置当前项目的一些基本信息

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket customDocket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.os467.controller"))
                .build();
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("团队名","http://www.my.com","my@my.com");
        return new ApiInfoBuilder()
                .title("文档标题")
                .description("文档描述")
                .contact("联系方式")
                .version("1.1.0")
                .build();
    }

}

转载请注明来源，欢迎对文章中的引用来源进行考证，欢迎指出任何有错误或不够清晰的表达。可以邮件至 1300452403@qq.com