Spring Boot 使用 Swagger 的 REST API 文档

REST 代表具象状态传输。 REST 是一种架构设计模式，它定义了 Web 服务开发中使用的约束。

Swagger 是一个开源 API 文档框架，用于记录其余 API。它提供了 API 文档的 HTML 视图，以及 JSON 支持和有关 HTTP 方法的详细信息。 REST API 设计用于某些类型的应用程序。

使用 Swagger 记录 API 有两个主要步骤：项目设置和设置 Swagger。

创建一个控制器类（模型类），该类将作为 JSON 响应发送。

public class Tweet { 
    private Integer id; 
  
    private String title; 
  
    private String msg; 
  
    public Integer getId() { 
        return id; 
    } 
  
    public void setId(Integer id) { 
        this.id = id; 
    } 
  
    public String getTitle() { 
        return title; 
    } 
  
    public void setTitle(String title) { 
        this.title = title; 
    } 
  
    public String getMsg() { 
        return msg; 
    } 
  
    public void setMsg(String msg) { 
        this.msg = msg; 
    } 
}

现在创建一个服务类来执行addTweet 和getTweet

import org.springframework.stereotype.Service; 
import java.util.ArrayList; 
import java.util.List; 
  
@Service
public class TweetService { 
    private List<Tweet> tweetList = new ArrayList<>(); 
  
    public void addTweet(){ 
        Tweet tweet = new Tweet(); 
        tweet.setId(1); 
        tweet.setTitle("My first tweet"); 
        tweet.setMsg("This is a dummy tweet for demonstration purposes."); 
        tweetList.add(tweet); 
  
        Tweet tweet2 = new Tweet(); 
        tweet2.setId(2); 
        tweet2.setTitle("My second tweet"); 
        tweet2.setMsg("This is the second dummy tweet for demonstration purposes."); 
        tweetList.add(tweet2); 
    } 
  
    public List<Tweet> getTweets() { 
        return tweetList; 
    } 
  
  
}

现在创建 RestController 类。

import org.springframework.beans.factory.annotation.Autowired; 
import org.springframework.web.bind.annotation.*; 
import java.util.List; 
  
@RestController
public class TweetController { 
    @Autowired
    private TweetService tweetService; 
  
    @PostMapping("/add") 
    public void addTweet() { 
        tweetService.addTweet(); 
    } 
  
    @GetMapping("/view") 
    public List<Tweet> viewTweets() { 
        return tweetService.getTweets(); 
    } 
  
    @GetMapping("/hello") 
    public String hello(){ 
        return "Hello World!"; 
    } 
}

@RestController 注解将类标记为 REST 控制器，负责处理 HTTP 请求并以 RESTful 方式生成响应。现在使用curl发出post请求。

curl --request POST \
  --url http://localhost:8080/add

转到 URL http://localhost:8080/view。

设置 Swagger
第1步：添加Maven依赖
要在 Spring Boot 应用程序中使用 Maven 依赖项启用 Swagger，请在构建配置 (pom.xml) 文件中添加以下依赖项。

<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>

运行mvn clean install

第 2 步：配置主类
启用主应用程序文件以使用 Swagger。

@EnableSwagger2 用于此，启用后，主应用程序文件应如下所示：

import org.springframework.boot.SpringApplication; 
import org.springframework.boot.autoconfigure.SpringBootApplication; 
import org.springframework.web.servlet.config.annotation.EnableWebMvc; 
  
import springfox.documentation.swagger2.annotations.EnableSwagger2; 
  
@SpringBootApplication
@EnableSwagger2
@EnableWebMvc
public class SwaggerApplication { 
    public static void main(String[] args) { 
        SpringApplication.run(SwaggerApplication.class, args); 
    } 
}

配置Swagger

import org.springframework.context.annotation.Configuration; 

import springfox.documentation.builders.PathSelectors; 
import springfox.documentation.builders.RequestHandlerSelectors; 
import springfox.documentation.spi.DocumentationType; 
import springfox.documentation.spring.web.plugins.Docket; 

@Configuration
public class SwaggerConfig { 

public Docket SwaggerApi() { 
    return new Docket(DocumentationType.SWAGGER_2) 
            .select() 
            .apis(RequestHandlerSelectors.any()) 
            .paths(PathSelectors.any()) 
            .build(); 
}

以下网址提供了 json 格式的文档： http://server:port/v2/api-docs
server：服务器名称或 IP
port：服务器端口

文档可从以下网址获取，用户界面为 http://server:port/swagger-ui/index.html/