SpringBoot整合swaggerUI

October 29, 2020 4273

什么是 Swagger?

Swagger™的目标是为REST APIs 定义一个标准的，与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。 
浏览 Swagger-Spec 去了解更多关于Swagger 项目的信息，包括附加的支持其他语言的库。

Swagger的官网为：https://swagger.io/

废话不多说直接开始：

在pom.xml添加依赖：

1
2
3
4
5
6
7
8
9
10
11
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>

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

写一个配置文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
package com.silin.pet.configuration;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * Create by silin
 * Date:  2019/5/26 15:50
 */
@Configuration
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.silin.pet.controller")) //填写控制层的包名
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档") 
                .description("简单优雅的restfun风格，http://localhost:8081/pet/index")
                .termsOfServiceUrl("http://localhost:8081/pet/index")
                .version("1.0")
                .build();
    }
}

在Application.java中配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
package com.silin.pet;

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@MapperScan("com.silin.pet.mapper")
@EnableSwagger2
public class PetApplication {

    public static void main(String[] args) {
        SpringApplication.run(PetApplication.class, args);
    }

}

在控制层添加注解:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
package com.silin.pet.controller;

import com.silin.pet.domain.PetProperty;
import com.silin.pet.service.PetService;
import com.silin.pet.vo.ResultVO;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

/**
 * Create by silin
 * Date:  2019/5/26 15:56
 */
@RestController
@RequestMapping("/pet")
public class PetController {

    @Autowired
    private PetService petService;

    @ApiOperation(value="获取宠物列表", notes="获取宠物列表")
    @GetMapping("/list")
    public ResultVO list(){
        List<PetProperty> petPropertyList = petService.findByPetPropertyAll();
        return  ResultVO.success(petPropertyList);
    }

    @ApiOperation(value="获取在线宠物的列表", notes="获取在线宠物的列表")
    @GetMapping("/statusList")
    public ResultVO statusList(){
        List<PetProperty> petPropertyList = petService.findByPetPropertyStatus();
        return ResultVO.success(petPropertyList);
    }

}

image.png

常用注解：

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

致谢

感谢您到来，如对您有帮助，请给小编一点温暖~~

查看评论