1 背景
springBoot作为微服务首选框架，为其他服务提供大量的接口服务。接口对接方需要实时最近的接口文档。
swagger可以通过代码和注释自动为web项目生成在线文档，这里使用swagger。
swagger官网地址：https://swagger.io/
2 使用
2.1 maven依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>依赖说明：
（1）springfox-swagger2
检测spring的web请求信息，生成检测结果（json格式）。
（2）springfox-swagger-ui
根据springfox-swagger2生成的数据，生成可视化的友好页面。
2.2 配置代码
Springfox提供Docket对象，为其设置相关属性，将其注册成为spring的bean后，可以在接口文档中展示（可配置多个Docket的bean，对应不同分组的接口）
package com.sxpcwlkj.product_server.config;
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 Swagger2Conf {
@Bean
public Docket getUserDocket(){
ApiInfo apiInfo=new ApiInfoBuilder()
.title("API-DOC")//api标题
.description("接口文档")//api描述
.version("1.0.0")//版本号
.contact("XiJue")//本API负责人的联系信息
.build();
return new Docket(DocumentationType.SWAGGER_2)//文档类型（swagger2）
.apiInfo(apiInfo)//设置包含在json ResourceListing响应中的api元信息
.select()//启动用于api选择的构建器
.apis(RequestHandlerSelectors.basePackage("com.sxpcwlkj.product_server.controller"))//扫描接口的包
.paths(PathSelectors.any())//路径过滤器（扫描所有路径）
.build();
}
}其中@Configuration、@Bean均为spring初始化bean相关的注解。@EnableSwagger2表示启用swagger2。
2.3 接口配置
通过在控制器和接口方法上加上相关注解，可以给接口和控制器添加相关的接口说明信息。
常用注解如下：
| 注解 | 使用地方 | 用途 |
| @Api | 类/接口 | 描述类/接口主要用途 |
| @ApiOperation | 方法 | 描述方法的用途 |
| @ApiImplicitParam | 方法 | 用于描述接口的非对象参数 |
| @ApiImplicitParams | 方法 | 用于描述接口的非对象参数集 |
| @ApiIgnore | 类/方法/参数 | Swagger 文档不会显示拥有该注解的接口 |
| @ApiModel | 参数实体类 | 可设置接口相关实体的描述 |
| @ApiModelProperty | 参数实体类属性 | 可设置实体属性的相关描述 |
package com.sxpcwlkj.product_server.entity;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import com.google.inject.internal.asm.$Type;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import java.math.BigDecimal;
@Data
@AllArgsConstructor
@NoArgsConstructor
//类名和数据库的表映射不一致时可以用此注解指定
//@TableName(value = "p_product")
@ApiModel("商品")
public class Product {
@ApiModelProperty("商品ID")
@TableId(type = IdType.AUTO)
private int productId;
@ApiModelProperty("商品标题")
private String productTitle;
@ApiModelProperty("商品价格")
private BigDecimal productPice;
@ApiModelProperty("商品库存")
private int productNum;
}
package com.sxpcwlkj.product_server.controller;
import com.sxpcwlkj.product_server.entity.Product;
import com.sxpcwlkj.product_server.mapper.ProductMapper;
import com.sxpcwlkj.product_server.utils.JsonResultObject;
import io.swagger.annotations.Api;
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;
@RestController
@RequestMapping("/api/v1/product")
@Api(tags = "商品管理模块")
public class ProductController {
@Autowired
private ProductMapper productMapper;
@ApiOperation(value = "ID查询商品", notes = "id为商品ID必填，数字")
@GetMapping("selectById")
public JsonResultObject selectById(int id) {
Product product = productMapper.selectById(id);
return JsonResultObject.getSuccessResult(product, "查询成功!");
}
}
http://localhost:8771/swagger-ui.html
