Swagger 2 有它不迷路，10分钟快速掌握

目录

Swagger2

一、简介

二、使用

1.maven导入Swagger

2.创建Swagger2配置类

3.接口文档测试地址​​​​​​​

4.常用注解说明

补充： 

更好看的ui风格

---

Swagger2

一、简介

一般我们在对接前后端的时候，都需要提供相应的接口文档。对于后端来说，编写接口文档即费时费力，还会经常因为没有及时更新，导致前端对接时出现实际接口与文档不一致。而且手写接口文档还容易出错，而swagger很好的解决了这个痛点。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。可用于：1.接口的文档在线自动生成、2.功能测试。

二、使用

1.maven导入Swagger

目前企业用的最多的版本还是2.x，这里推荐使用

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
​
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

2.创建Swagger2配置类

这个配置类复制过去改改就好了~

实际开发中，我们可能针对不同的开发人员或者开发模块，单独分组设置api接口文档。

如下就对应了三种接口文档~

如果你嫌麻烦，也可以只用一组~

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket webAllConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                // 组名
                .groupName("webAllApi") 
                .apiInfo(webAllInfo())
                .select()
                //显示当前所有接口
                .paths(PathSelectors.any())
                // 不显示/error下的接口（swagger自带的）
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build();
​
    }
​
    private ApiInfo webAllInfo(){
        return new ApiInfoBuilder()
                .title("天猫猫商城-所有文档")
                .description("本文档描述了网站微服务接口定义")
                .version("1.0")
                .contact(new Contact("hssy", "https://www.baidu.com", "123456@qq.com"))
                .build();
    }
​
​
​
    @Bean
    public Docket frontApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("frontApi")
                .apiInfo(frontApiInfo())
                .select()
                //只显示api路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/api/.*")))
                .build();
​
    }
    private ApiInfo frontApiInfo(){
        return new ApiInfoBuilder()
                .title("前台网站-API文档")
                .description("本文档描述了网站微服务接口定义")
                .version("1.0")
                .contact(new Contact("hssy", "https://www.baidu.com", "123456@qq.com"))
                .build();
    }
    
    
    @Bean
    public Docket adminApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("adminApi")
                .apiInfo(adminApiInfo())
                .select()
                //只显示admin路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                .build();
​
    }
    private ApiInfo adminApiInfo(){
        return new ApiInfoBuilder()
                .title("后台管理系统-API文档")
                .description("本文档描述了后台管理系统微服务接口定义")
                .version("1.0")
                .contact(new Contact("hssy", "https://www.baidu.com", "123456@qq.com"))
                .build();
    }
}

3.接口文档测试地址

ip:port/swagger-ui.html

 

4.常用注解说明

先记住以下四个最常用的~

@Api : 用在类上，用来指定接口的描述文字

@RestController
@RequestMapping("/newcustomer/industry")
@Api(tags = "行业标签接口")
public class IndustryController {
    @Autowired
    private IndustryService industryService;

@ApiOperation：用在方法上，用来对接口中具体方法做描述

value：对接口的总体描述

notes：对接口的详细描述

httpMethod:请求方式，必须要和@RequestMapping保持一致

@GetMapping("/findAll")
@ApiOperation(value = "查询所有行业标签",notes = "查询所有行业标签，这里是详细描述信息！",httpMethod = "GET")
public Result<List<Industry>> findAll(){
    return industryService.findAll();
}

 @ApiModel：作用在类上，用来描述一个实体类信息

value：类名

description：实体类描述

@ApiModel(value = "Industry对象", description = "行业标签")
public class Industry implements Serializable {
​
    private static final long serialVersionUID = 1L;
​
    @ApiModelProperty("主键id")
    @TableId(value = "id", type = IdType.AUTO)
    private Integer id;

@ApiModelProperty：作用在类的属性上，用来描述一个实体类的属性

value：默认属性，类属性描述

@ApiModelProperty("标签名称")
@TableField("name")
private String name;

或者

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

补充： 

更好看的ui风格

这里再推荐一种更好看的ui界面，只需要引入另外一个jar包。

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.3</version>
</dependency>

当然了，它和原来的springfox-swagger-ui依赖并不冲突，你也可以不要原来的ui，就不用导入springfox-swagger-ui这个依赖，直接替换就可以了。

然后我们启动项目，只需访问ip:port/swagger-ui.html即可。