Springboot 整合 Swagger-UI 实现在线 API 文档_小言_互联网的博客

Springboot 整合 Swagger-UI 实现在线 API 文档

2021-05-24 15:36 188人阅读评论(0)

常用注解
@Api：用于修饰Controller类，生成Controller相关文档信息
@ApiOperation：用于修饰Controller类中的方法，生成接口方法相关文档信息
@ApiParam：用于修饰接口中的参数，生成接口参数相关文档信息
@ApiModelProperty：用于修饰实体类的属性，当实体类是请求参数或返回结果时，直接生成相关文档信息

在pom.xml中新增Swagger-UI相关依赖

     <!--Swagger-UI API文档生产工具-->
        <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>

添加Swagger-UI的配置


package com.jq.swagger;

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 SwaggerConfig {
   

    @Bean
    public Docket createRestApi(){
   
           //访问地址：http://localhost:8080/swagger-ui.html#/
           //不一定是8080,启用那个服务就用那个端口
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包下controller生成API文档
                .apis(RequestHandlerSelectors.basePackage("com.jq.order.controller"))
                //为有@Api注解的Controller生成API文档
         //.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //为有@ApiOperation注解的方法生成API文档
            //  .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
   
        return new ApiInfoBuilder()
                .title("订单模块api接口文档")   // 文档标题
                .description("订单模块api接口文档")  // 文档描述
                .contact("jq")  // 设置联系人
                .version("1.0")  //版本号
                .build();
    }

}

controller控制器中

package com.jq.order.controller;


import com.jq.idempotence.IdempotenceAnnotation;
import com.jq.order.model.OmsOrder;
import com.jq.order.model.OmsOrderItem;
import com.jq.order.service.OmsOrderService;
import com.jq.result.ResultObj;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import javax.servlet.http.HttpServletRequest;
import java.util.List;

/**
 * <p>
 * 订单表 前端控制器
 * </p>
 *
 * @author jq
 * @since 2021-04-18
 */
@RestController
@RequestMapping("/order")
@Api(tags = "OmsOrderController", description = "订单管理")
public class OmsOrderController {
   


    @Autowired
    private OmsOrderService omsOrderService;

    @Autowired
    private HttpServletRequest request;

    @ApiOperation("创建订单")
    @PostMapping
    @IdempotenceAnnotation
    public ResultObj createOrder(@ApiParam("地区id")    @RequestParam("addressId") Integer addressId,
                                 @ApiParam("支付方式") @RequestParam("payType") Integer payType,
                                 @ApiParam("商品编码") @RequestParam("skeCode") String skeCode){
   

        String phone = request.getHeader("phone");
        String userId = request.getHeader("userId");
       ResultObj resultObj= omsOrderService.createOrder(addressId,payType,phone,userId,skeCode);
       return resultObj;
    }
}

实体类上加注释

package com.jq.order.model;

import java.math.BigDecimal;
import com.baomidou.mybatisplus.annotation.IdType;
import java.util.Date;
import com.baomidou.mybatisplus.annotation.TableId;
import java.io.Serializable;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.EqualsAndHashCode;

/**
 * <p>
 * 订单表
 * </p>
 *
 * @author jq
 * @since 2021-04-18
 */
@Data
@EqualsAndHashCode(callSuper = false)
@ApiModel(value="rder对象",description="订单对象order")
public class OmsOrder  implements Serializable {
   

    private static final long serialVersionUID = 1L;

    /**
     * 订单id
     */
    @ApiModelProperty(value="订单id",name="id")
    @TableId(value = "id", type = IdType.AUTO)
    private Long id;

    /**
     * 会员ID
     */
    @ApiModelProperty(value="会员ID",name="memberId")
    private Long memberId;

    /**
     * 优惠券ID
     */
    @ApiModelProperty(value="优惠券ID",name="couponId")
    private Long couponId;

    /**
     * 订单编号
     */
    @ApiModelProperty(value="订单编号",name="orderSn")
    private String orderSn;

    /**
     * 提交时间
     */
    @ApiModelProperty(value="提交时间",name="createTime")
    private Date createTime;

    /**
     * 用户帐号
     */
    @ApiModelProperty(value="用户帐号",name="memberUsername")
    private String memberUsername;

    /**
     * 订单总金额
     */
    @ApiModelProperty(value="订单总金额",name="totalAmount")
    private BigDecimal totalAmount;

    /**
     * 应付金额（实际支付金额）
     */
    @ApiModelProperty(value="应付金额",name="payAmount")
    private BigDecimal payAmount;

    /**
     * 运费金额
     */
    @ApiModelProperty(value="运费金额",name="freightAmount")
    private BigDecimal freightAmount;

    /**
     * 促销优化金额（促销价、满减、阶梯价）
     */
    @ApiModelProperty(value="促销优化金额",name="promotionAmount")
    private BigDecimal promotionAmount;

    /**
     * 积分抵扣金额
     */
    @ApiModelProperty(value="积分抵扣金额",name="integrationAmount")
    private BigDecimal integrationAmount;

    /**
     * 优惠券抵扣金额
     */
    @ApiModelProperty(value="优惠券抵扣金额",name="couponAmount")
    private BigDecimal couponAmount;


}