Spring Boot 使用 swagger 实现Rest Api 文档化

zhangdy0 2019-04-23

Swagger 是一个简单、功能强大、非常流行的API 表达工具。基于Swagger 生成API,可以得到交互式文档、自动生成代码的SDK,以及API 的发现方式。

Swagger 允许用户在一个html5 web 页面中,对API 进行文档化和交互。

优点:

  • 功能丰富:支持多种注解,自动生成接口文档界面,支持在界面测试API接口功能;
  • 及时更新:开发过程中花一点写注释的时间,就可以及时的更新API文档,省心省力;
  • 整合简单:通过添加pom依赖和简单配置,内嵌于应用中就可同时发布API接口文档界面,不需要部署独立服务。

如下是自动生成的API 文档界面:

Spring Boot 使用 swagger 实现Rest Api 文档化

实现 Swagger 文档

1. 添加依赖

主要是 添加 swagger2 核心包 以及 swagger-ui界面包的依赖。

<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. 编写Swagger的配置类

package com.rickie;

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;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration

@EnableSwagger2

public class Swagger2 {

@Bean

public Docket createRestApi() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

.select()

.apis(RequestHandlerSelectors.basePackage("com.rickie.rest"))

.paths(PathSelectors.any())

.build();

}

private ApiInfo apiInfo() {

return new ApiInfoBuilder()

.title("Swagger构建RESTful API")

.description("")

.termsOfServiceUrl("")

.version("1.0")

.build();

}

}

3. 在controller 中编写自己的api 文档,主要是参数和接口的描述

如下是ProductController.java 的示例代码。

package com.rickie.rest;

import com.rickie.dto.Product;

import io.swagger.annotations.ApiImplicitParam;

import io.swagger.annotations.ApiOperation;

import org.springframework.web.bind.annotation.PathVariable;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RequestMethod;

import org.springframework.web.bind.annotation.RestController;

import java.util.ArrayList;

import java.util.List;

@RestController

@RequestMapping(value="/products") // 通过这里配置使下面的映射都在/products下

public class ProductController {

private List<Product> productList;

//初始化

public ProductController(){

productList = new ArrayList<Product>();

for (int i = 0; i < 10; i++) {

Product product =new Product();

product.setId(i);

product.setCount(i+10);

product.setName("watch"+i);

product.setDesc("watch desc"+i);

productList.add(product);

}

}

@ApiOperation(value="获取产品列表", notes="获取产品列表")

@RequestMapping(value={""}, method= RequestMethod.GET)

public List<Product> getProductList() {

return productList;

}

@ApiOperation(value="获取产品详细信息", notes="根据url的id来获取产品详细信息")

@ApiImplicitParam(name = "id", value = "产品ID", required = true, dataType = "Integer",paramType="path")

@RequestMapping(value="/{id}", method=RequestMethod.GET)

public Product getProduct(@PathVariable Integer id) {

return productList.get(id);

}

}

@ApiOperation:

作用在方法上,表示一个http请求的操作 。

@ApiImplicitParam:

作用在方法上,表示单独的请求参数

参数:

1. name :参数名。

2. value : 参数的具体意义,作用。

3. required : 参数是否必填。

4. dataType :参数的数据类型。

5. paramType :查询参数类型,这里有几种形式:

@ApiImplicitParams:

用于方法,包含多个 @ApiImplicitParam。

@Api:

作用在类上,用来标注该类具体实现内容。标识这个类是swagger的资源 。

参数:

1. tags:允许您为操作设置多个标签的属性。

2. description:可描述该类的作用。

4. 启动应用程序,访问Swagger

访问如下链接,可以看到第一张图片所示,显示所有的API 列表方法。

http://localhost:8080/swagger-ui.html

点击查看第一个方法/products,如下图所示,可以进行交互操作。

Spring Boot 使用 swagger 实现Rest Api 文档化

访问 http://localhost:8080/v2/api-docs 可以获取接口的JSON 描述文件,如下图所示。

Spring Boot 使用 swagger 实现Rest Api 文档化

相关推荐