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;
}