IT序号网

Spring 集成 Swagger知识解答

leader 2021年05月27日 编程语言 148 0

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


发布评论
IT序号网

微信公众号号:IT虾米 (左侧二维码扫一扫)欢迎添加!

idea 新建/导入的xml 报文头报错 URI is not registered (Settings | Languages & Frameworks | Schemas and DTDs)知识解答
你是第一个吃螃蟹的人
发表评论

◎欢迎参与讨论,请在这里发表您的看法、交流您的观点。