SpringBoot中Swagger的構建和遇見坑

原創

2020-02-21 03:18

一、構建swagger UI文檔

1、加入依賴

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.1.0.RELEASE</version>
    <relativePath/> <!-- lookup parent from repository -->
  </parent>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <java.version>1.8</java.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
      <groupId>mysql</groupId>
      <artifactId>mysql-connector-java</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.projectlombok</groupId>
      <artifactId>lombok</artifactId>
      <scope>provided</scope>
    </dependency>
    <!-- swagger 依賴 -->
    <dependency>
      <groupId>com.spring4all</groupId>
      <artifactId>swagger-spring-boot-starter</artifactId>
      <version>1.9.0.RELEASE</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>

基於1.9.0.RELEASE的swagger要求配置好基本信息才能使用swagger文檔，否則會有Basic Error Controller的錯誤，在application.yml配置如下：

swagger:
  base-path: /**
  title: "接口文檔"
  description: "接口文檔描述"
  version: 1.9.0.RELEASE
  license: Apache License, Version 2.0
  licenseUrl: https://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    name: zhongbao
    url: https://blog.csdn.net/Haihao_micro
    email: *************@qq.com
  base-package: com.zbz

Application的加上@EnableSwagger2Doc開啓使用

@EnableSwagger2Doc
@SpringBootApplication(scanBasePackages = "com.zbz")
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class,args);
    }
}

在com.zbz下使用@Api(tags = “用戶/管理”)註解UserController

@Api(tags = "用戶/管理")
@RestController
@RequestMapping(value = "/user")
public class UserController {

    @Autowired
    UserDao userDao;

    @GetMapping("/")
    @ApiOperation(value = "獲取用戶列表")
    public List<User> getUserList() {
        List<User> r = userDao.findAll();
        return r;
    }
}

以上配置完畢，一個swagger文檔就可以訪問使用，http://localhost:8080/swagger-ui.html