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

我就是我 2024-04-03 08:04 44阅读 0赞

**目录**

Swagger2

一、简介

二、使用

1.maven导入Swagger

2.创建Swagger2配置类

3.接口文档测试地址

4.常用注解说明

补充：

更好看的ui风格

--------------------

## Swagger2 ##

### 一、简介 ###

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

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

### 二、使用 ###

#### 1.maven导入Swagger ####

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

<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.创建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

#### ![b15eccc104f2495191508de039902e58.png][] ####

![9b76de24db9549688f592ea4475f4041.png][]

![6a89da3df2854108ba119425553b21ca.png][]

#### 4.常用注解说明 ####

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

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

>     @RestController
>     @RequestMapping("/newcustomer/industry")
>     @Api(tags = "行业标签接口")
>     public class IndustryController {
>         @Autowired
>         private IndustryService industryService;
> 
> ![5512d78916924d5d97ad5734245a4a7f.png][]

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

> `value`：对接口的总体描述
> 
> `notes`：对接口的详细描述
> 
> `httpMethod`:请求方式，必须要和@RequestMapping保持一致
> 
>     @GetMapping("/findAll")
>     @ApiOperation(value = "查询所有行业标签",notes = "查询所有行业标签，这里是详细描述信息！",httpMethod = "GET")
>     public Result<List<Industry>> findAll(){
>         return industryService.findAll();
>     }
> 
> ![7401aa869ce4448383f061e93c4f9a8c.png][]

@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;
> 
> ![9bc283cf038e45ff9332fe21aad82267.png][]

## 补充： ##

### 更好看的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即可。

![72fbc0854b2b4765b919ca053de35fc7.png][]

![d63383ac5f8640178f5d97413f71d090.png][]

![acd0d6fe36ba45e7bd449dc4a08b30b5.png][]

![8645de427e53441a9cf9aeacbf07ccc3.png][]

[b15eccc104f2495191508de039902e58.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/03/8efb343c9c9442c494227735db7310bc.png
[9b76de24db9549688f592ea4475f4041.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/03/f19ec833a6214263993983e984bc6451.png
[6a89da3df2854108ba119425553b21ca.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/03/a8de11c4afa74d47b9869594304a7004.png
[5512d78916924d5d97ad5734245a4a7f.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/03/1b0d93a690634e4888ca327d2aa21206.png
[7401aa869ce4448383f061e93c4f9a8c.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/03/dad79cd529b44b07b812c02318733801.png
[9bc283cf038e45ff9332fe21aad82267.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/03/89e53395d5a546fa8b2572374e9ebc26.png
[72fbc0854b2b4765b919ca053de35fc7.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/03/1fa341b30a904076b0bb6a4769226058.png
[d63383ac5f8640178f5d97413f71d090.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/03/6e5bede050c142b7ad8a14bbd1466233.png
[acd0d6fe36ba45e7bd449dc4a08b30b5.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/03/ed0813a084cd4dfdb417d3915edbe134.png
[8645de427e53441a9cf9aeacbf07ccc3.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/03/de399750d4a347b895c04583190b2460.png