Spring Boot&Swagger构建REST API并生成API文档

什么是Swagger？

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。

 

前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要， Swagger就是一款让你更好的书写API文档的框架。

 

Swagger的优点？

官方说法： Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

 

不难看出， Swagger的一个最大的优点是能实时同步api与文档。

· 引入Maven依赖

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>1.5.8.RELEASE</version>
    <relativePath/><!-- lookup parent from repository -->
</parent>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- Swagger -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.2.2</version>
        </dependency>
    <dependency>
       	<groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.2.2</version>
    </dependency>
</dependencies>

· 创建Application主类

package nextdms;//注意包结构 
    @SpringBootApplication 
    public class Application { 
    public static void main(String[] args) throws Exception {
        SpringApplication.run(Application.class, args); 
    } 
}

· 在启动application的相同目录下创建Swagger配置类

package nextdms;//注意包结构 
@Configuration
@EnableSwagger2
public class Swagger2Configuration {
    @Bean
    public Docket buildDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInf())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.nextdms.crm.controller"))//要扫描的API(Controller)基础包	    
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo buildApiInf() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2 UI构建API文档")
                .contact("土豆")
                .version("1.0")
                .build();
    }
}

· 创建RestController 构建一个简单计算服务API

package nextdms.controller.logis.inven;//注意包结构

@Api(value = "计算服务",description="简单的计算服务，提供加减乘除运算API")
@RestController
@RequestMapping("/compute")
public class ComputeController {
      @ApiOperation("加法运算")
      @PostMapping("/add")
      public Double add(@RequestParam Double a,  @RequestParam Double b) {
         return a + b;
      }
   
      @ApiOperation("减法运算")
      @PostMapping("/sub")
      public Double sub(@RequestParam Double a,  @RequestParam Double b) {
          return a - b;
      }

      @ApiOperation("乘法运算")
      @PostMapping("/mul")
      public Double mul(@RequestParam Double a,  @RequestParam Double b) {
          return a * b;
      }

      @ApiOperation("除法运算")
      @PostMapping("/div")
      public Double div(@ApiParam("被除数")@RequestParam Double a, @ApiParam("除数")@RequestParam   Double b) {
          return a / b;
      }
}

注：

@Api注解用来表述该服务的信息，如果不使用则显示类名称.

@ApiOperation注解用于表述接口信息

@ApiParam注解用于描述接口的参数

在GET请求中，使用@RequestParam注解来接受Http请求参数。

在POST请求，可使用@RequestBody和@RequestParam。

 

通过上面几步我们已经成功构建了一个具备加减乘除的计算服务API，并且已经拥有一份不错的在线文档了，现在我们来启动它，执行mvn spring-boot:run，或直接运行Application.main()。

 

启动成功后，访问 http://localhost:8080/swagger-ui.html，便可以看到我们刚才构建的计算服务的API文档了。（注意：端口号可能不一样）

 

效果如下：

 

 

 

Swagger UI不仅仅是文档，还提供了在线API调试的功能，我们可以调试下我们的除法运算API。

点击Try it out！后可以看到我们成功的调用了除法运算API并获得了正确的响应。

本示例完整代码的GIT地址 点击我~

Swagger-Core文档 点击我~

SpringFox文档 点击我~

Spring Boot 文档 点击我~

更多相关注解 点击我~

作者：简单的土豆

链接：https://www.jianshu.com/p/c5cb33ad4305

來源：简书

著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。

 

一个从装环境开始的学习记录公众号，欢迎大家关注：