001、swagger2集成使用

悟空2016

于 2024-09-11 14:07:33 发布

阅读量309

点赞数 6

分类专栏： # 2、SpringBoot 文章标签： java

本文链接：https://blog.csdn.net/king27001/article/details/142138303

版权

2、SpringBoot 专栏收录该内容

4 篇文章 0 订阅

订阅专栏

https://blog.csdn.net/JokerLJG/article/details/123544934
https://www.cnblogs.com/mystarry/p/17740463.html

1. 引入jar

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

2. 添加配置 Swagger2Configuration

package com.XX.ms.msplat.config;


import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

/**
 * Swagger2配置
 *
 * @author 20004855
 */
@Configuration
@EnableSwagger2
@ConditionalOnProperty(prefix = "swagger", value = "enabled", havingValue = "true")
public class Swagger2Configuration {

    static final String SWAGGER_SCAN_PACKAGE = "com.xx.ms.msplat";

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("微服务脚手架API文档")
                        .description("微服务脚手架API文档")
                        .version("1.0.0")
                        .build())
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_PACKAGE))
                .paths(PathSelectors.any())
                .build()
                // 添加swagger head参数配置
                .globalOperationParameters(this.getParameterList());
    }

    /**
     * 添加swagger head参数配置
     */
    private List<Parameter> getParameterList() {
        ParameterBuilder clientIdTicket = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        clientIdTicket.name("Access-Token").description("token令牌")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                //设置false，表示clientId参数 非必填,可传可不传！
                .required(false).build();
        pars.add(clientIdTicket.build());
        return pars;
    }
}

3. 注解

@Api Controller级别

@Api(value = "消息", tags = {"消息"})
@RestController
@RequestMapping("")
public class MessageController {

@ApiOperation method级别

@ApiOperation 方法注释，response属性表示swagger中返回的数据类型。

@ApiOperation(value = "6.二级分类消息列表详情接口", response = MsgList4AllSecondTypeResp.class)
@PostMapping(Constants.CLIENT_BASE_URL + "/message/msgList4AllSecondType")
public JsonResult<List<MsgList4AllSecondTypeResp>> msgList4AllSecondType(@Valid @RequestBody MsgFirstTypeIdReq msgFirstTypeIdReq) {
    List<MsgList4AllSecondTypeResp> list = msgDetailService.msgList4AllSecondType(msgFirstTypeIdReq.getMsgFirstTypeId());
    return JsonResult.success(list);
}

@ApiModel @ApiModelProperty 入参，出参

 @ApiModelProperty position属性控制swagger的参数顺序，hidden控制在swagger中的显隐。
 效果如下图：

在这里插入图片描述

package com.XX.ms.cartechmessageservice.model.vo.message.resp;

import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import com.fasterxml.jackson.databind.ser.std.ToStringSerializer;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.util.Date;

@Data
@ApiModel("消息一级分类列表接口返回参数")
public class MsgList4AllFirstTypeResp {

    @ApiModelProperty(value = "一级分类的id", position = 1)
    @JsonSerialize(using = ToStringSerializer.class)
    private Long msgFirstTypeId;

    @ApiModelProperty(value = "一级分类的名称", position = 2)
    private String msgFirstTypeName;

    @ApiModelProperty(value = "一级分类的图标", position = 3)
    private String iconSrc;

    @ApiModelProperty(value = "一级分类的消息数量", position = 4)
    @JsonSerialize(using = ToStringSerializer.class)
    private Integer count;

    @ApiModelProperty(value = "最新一条消息的内容", position = 5)
    private String content;

    @ApiModelProperty(value = "最新一条消息的内容的发送时间", position = 6, hidden = true)
//    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
    private Date gmtCreate;

    @ApiModelProperty(value = "一级分类的消息数量的颜色：red，gray", position = 7)
    private String msgCountColor;

    @ApiModelProperty(value = "消息显示时间：未超过60min【xx分钟前】，超过60min按【xx小时前】、超过24h按【xx天前】", position = 8)
    private String msgShowTime;
}