Spring Boot

SpringBoot集成swagger2

微信扫一扫,分享到朋友圈

SpringBoot集成swagger2
收藏 0 0

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
展开阅读全文
干一件事情,用心干就完了
上一篇

谷歌浏览器安装json格式化插件

你也可能喜欢

发表评论

您的电子邮件地址不会被公开。 必填项已用 * 标注

提示:点击验证后方可评论!

插入图片

分类目录

微信扫一扫

微信扫一扫