开发者社区> 享智同行> 正文
阿里云
为了无法计算的价值
打开APP
阿里云APP内打开

如何让接口文档自动生成,SpringBoot中Swagger的使用

简介: 在开发过程中,java后端需要与客户端进行交互,需要将后端的接口及参数写成文档给调用者查阅。一个问题也有此而生,需求改动频繁,接口设计也会随之改动,文档修改的不及时会带来很大的问题。 Swagger是一个自动生成文档的工具,可以在线查阅文档,减少了开发人员的负担,下面我们就来看看如何在SpringBoot中使用Swagger。
+关注继续查看

在开发过程中,java后端需要与客户端进行交互,需要将后端的接口及参数写成文档给调用者查阅。一个问题也有此而生,需求改动频繁,接口设计也会随之改动,文档修改的不及时会带来很大的问题。

Swagger是一个自动生成文档的工具,可以在线查阅文档,减少了开发人员的负担,下面我们就来看看如何在SpringBoot中使用Swagger。

一、在SpringBoot项目中配置Swagger2

1、pom.xml中对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>

2、编写配置类启用Swagger

Swagger2Config.java

@Configuration //配置类
@EnableSwagger2 //启用Swagger2
public class Swagger2Config {
    @Bean
    public Docket apiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)//创建Swagger2类型的文档
                .apiInfo(apiInfo());//apiInfo方法返回配置的接口信息
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("用户中心微服务前台网站API")//接口标题
                .description("此文档描述了用户中心前台网站的基本API接口")//接口描述
                .version("1.0")//接口版本
                .contact(new Contact("Jack", "http://www.jikedaquan.com", "jikedaquan@163.com"))//联系方式:名字、网址、邮箱
                .build();
    }
}

3、配置实体类的文档

实体类Member

//对实体名生成文档描述
@ApiModel(value="Member对象")
public class Member{

    //对属性生成文档描述
    @ApiModelProperty(value = "学员ID")
    private Long memberId;

    //required 将属性描述标记为必须
    @ApiModelProperty(value = "手机号",required = true)
    private String mobile;

    @ApiModelProperty(value = "邮箱",required = true)
    private String email;

    @ApiModelProperty(value = "密码",required = true)
    private String password;

    @ApiModelProperty(value = "用户名")
    private String userName;

    //将不希望在文档中看到的属性使用hidden隐藏
    @ApiModelProperty(value = "逻辑删除 1已删除 0未删除",hidden = true)
    private Boolean deleted;

    //省略其他字段
}

4、配置接口的文档

控制器接口类

@RestController
//生成api接口的文档描述
@Api(description = "学员管理")
@RequestMapping("/ucenter/member")
public class MemberController {
    @Autowired
    private MemberService memberService;

    //定义请求方法的名字和详细描述
    @ApiOperation(value = "注册学员", notes = "updateTime,createTime无需添加,这是前台系统用户的注册功能,前提是用户已经接收了验证码")
    @PostMapping
    public boolean register(
            //定义请求参数的文档描述 name的值是要描述的参数的名字
            @ApiParam(name = "member", value = "学员对象", required = true)
            @RequestBody Member member) {
        boolean result = memberService.save(member);
        return result;
    }
    
    //省略其他
}

5、访问文档

文档地址:localhost:8080/swagger-ui.html

二、接口前后台分离的配置

为什么要对接口进行前后台分离?因为前台和后台的功能有些相同,但有些差异,例如后台管理员可以删除用户,但前台是没有删除用户的功能的,将接口和文档分离更有利于管理维护。

1、接口分离

前台接口

@RestController
@Api(description = "前端学员管理")
@RequestMapping("/api/ucenter/member")
public class MemberController {
    @Autowired
    private MemberService memberService;

    @ApiOperation(value = "注册学员", notes = "updateTime,createTime无需添加,这是前台系统用户的注册功能,前提是用户已经接收了验证码")
    @PostMapping
    public boolean register(
            @ApiParam(name = "member", value = "学员对象", required = true)
            @RequestBody Member member) {
        boolean result = memberService.save(member);
        return result;
    }
}

后台接口放在同级下的admin包中

@RestController
@Api(description = "学员管理")
@RequestMapping("/admin/ucenter/member")
public class AdminMemberController {
    @Autowired
    private MemberService memberService;

    @ApiOperation(value = "返回所有学员列表")
    @GetMapping
    public List<Member> list() {
        return memberService.list(null);
    }

    @ApiOperation(value = "根据id删除学员")
    @DeleteMapping(value = "{memberId}")
    public boolean deleteById(@ApiParam(name = "memberId", value = "学员id", required = true)
                              @PathVariable Long memberId) {
        boolean result = memberService.removeById(memberId);
        return result;
    }

    @ApiOperation(value = "注册学员", notes = "updateTime,createTime无需添加,这是前台系统用户的注册功能,前提是用户已经接收了验证码")
    @PostMapping
    public boolean register(
            @ApiParam(name = "member", value = "学员对象", required = true)
            @RequestBody Member member) {
        boolean result = memberService.save(member);
        return result;
    }
}

这样就有了同一个实体的不同的接口

2、对前后台接口进行分组配置

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    //前台api接口文档
    public Docket webApiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")//组名
                .apiInfo(webApiInfo())
                .select()//创建ApiSelectorBuilder对象
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))//过滤掉 admin 接口
                .paths(Predicates.not(PathSelectors.regex("/error.*")))//过滤掉 error 接口
                .build();
    }

    @Bean
    //后台管理员api文档
    public Docket adminApiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("adminApi")
                .apiInfo(adminApiInfo())
                .select()//创建ApiSelectorBuilder对象
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))//只显示 admin 接口
                .build();
    }

    private ApiInfo webApiInfo() {
        return new ApiInfoBuilder()
                .title("用户中心微服务前台网站API")
                .description("此文档描述了用户中心前台网站的基本API接口")
                .version("1.0")
                .contact(new Contact("Jack", "http://www.jikedaquan.com", "jikedaquan@163.com"))
                .build();
    }

    private ApiInfo adminApiInfo() {
        return new ApiInfoBuilder()
                .title("用户中心微服务后台管理系统的API")
                .description("此文档描述了用户中心后台管理系统的基本API接口")
                .version("1.0")
                .contact(new Contact("Jack", "http://www.jikedaquan.com", "jikedaquan@163.com"))
                .build();
    }
}

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
全栈开发之后端脚手架:SpringBoot集成MybatisPlus代码生成,分页,雪花算法,统一响应,异常拦截,Swagger3接口文档
全栈开发之后端脚手架:SpringBoot集成MybatisPlus代码生成,分页,雪花算法,统一响应,异常拦截,Swagger3接口文档
93 0
SpringBoot——SpringBoot集成Swagger生成API文档
SpringBoot——SpringBoot集成Swagger生成API文档
38 0
【Spring Boot实战与进阶】整合Swagger3生成接口文档
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
86 0
Python3+ Django3:自动生成Swagger接口文档
Python3+ Django3:自动生成Swagger接口文档
195 0
spring boot 下swagger2 的使用
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。 swagger 官方Demo供参考 https://petstore.swagger.io/ swagger注解 swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。 API详细说明 @Api(tags = "收付费方式变更") 常用 @ApiOperation("获取用户列表") 常用 @ApiParam(v
41 0
Spring Boot 2.x基础教程:Swagger静态文档的生成
Spring Boot 2.x基础教程:Swagger静态文档的生成
55 0
Springboot进阶-JDBC、Druid、Mybatis、Swagger、SpringMVC、Mail
Springboot进阶-JDBC、Druid、Mybatis、Swagger、SpringMVC、Mail
80 0
SpringBoot使用Swagger
讲解如何快速在SpringBoot项目使用Swagger
503 0
Spring3 MVC中使用Swagger生成API文档
Spring3 MVC中使用Swagger生成API文档 一:Swagger介绍 Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目 实现了与SpingMVC框架的无缝集成功能,方便生成spring restful风格的接口文档, 同时swagger-ui还可以测试spring restful风格的接口功能。
1565 0
+关注
享智同行
关注公众号【享智同行】第一时间获得技术干货
30
文章
0
问答
文章排行榜
最热
最新
相关电子书
更多
低代码开发师(初级)实战教程
立即下载
阿里巴巴DevOps 最佳实践手册
立即下载
冬季实战营第三期:MySQL数据库进阶实战
立即下载