Spring 集成 Swagger

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测

Swagger 的优势

　　支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术

　　提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口

现有项目使用的是spring框架 现需要集成Swagger，步骤如下：

　　1.添加依赖

<dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>1.5.21</version>
    </dependency>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-models</artifactId>
        <version>1.5.21</version>
    </dependency>
    <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>
    <dependency>
        <groupId>javax.servlet</groupId>
        <artifactId>javax.servlet-api</artifactId>
        <version>3.1.0</version>
    </dependency>

　　2.创建 Swagger 配置类

package com.swagger.config;

import io.swagger.annotations.Api;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
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;

@EnableWebMvc
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //Swagger 开关 配置在配置文件中 测试环境打开 生产环境关闭
    @Value(value = "${swagger.enabled:false}")
    private Boolean swaggerEnabled;

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 是否开启
                .enable(swaggerEnabled)
                .select()
                //只显示添加@Api注解的类
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXX系统")
                .description("接口文档")
                .version("1.0.0")
                .build();
    }
}

　　3.在spring.xml 增加扫描配置

 <!-- 扫描swagger包路径 -->
    <context:component-scan  base-package="com.swagger.config"/>

　　4.后续就可以在controller和entity中 增加注解生成API文档

@RestController
@RequestMapping(value = { "/commodity/" })
// 类上加@Api注解
@Api(value = "/CommodityController", tags = "商品查询接口")
public class CommodityController{
    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    // 方法上加ApiOpreation注解
    @ApiOperation(value = "根据id获取产品信息", notes = "根据id获取商品信息", httpMethod = "GET", response = Commodity.class)
    public ResponseEntity<Commodity> get(@PathVariable Long id) {
        Commodity commodity= new Commodity();
        commodity.setName("T恤");
        commodity.setId(1L);
        return ResponseEntity.ok(commodity);
    }
}

package com.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.util.Date;

@ApiModel(value = "商品列表查询参数")
@Data
public class Commodity {

    @ApiModelProperty(value = "商品名称")
    private String name;

    @ApiModelProperty(value = "商品 id")
    private long id;
}

　　5.在配置文件中配置开关：swagger.enabled=true  测试环境打开 生产环境关闭

就可以启动项目 访问：http://localhost:8080/项目名/swagger-ui.html  查看api