关于Swagger

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测

当存在一个RESTful 的项目，需要和别人对接时，为了方便阅读的你提供的接口。引入Swagger后，关于输入参数、返回参数和请求方式，都可以清晰的看见。方便api文档的管理，同时需要的话还可以作为api的测试工具。

Spring-Boot集成Swagger

1.添加依赖


           
               
    
     io.springfox
                
    
     springfox-swagger2
                
    
     2.5.0
            
           
           
               
    
     io.springfox
                
    
     springfox-swagger-ui
                
    
     2.5.0

2.Swagger配置

这里我使用的配置类和yml配置文件去整合的

yml配置

# swagger configcom.dl.demo.plugin.swagger:   enable: true   scan.package: com.dl.demo.controller

配置类

@Configuration@EnableSwagger2public class SwaggerConfig {
       @Value("${com.dl.demo.plugin.swagger.enable}")    private boolean swaggerEnable;    @Value("${com.dl.demo.plugin.swagger.scan.package}")    private String scanPackage;    @Bean    public Docket createRestApi() {
           return new Docket(DocumentationType.SWAGGER_2)                .enable(swaggerEnable)                .apiInfo(apiInfo())                .select()                //为当前包路径                .apis(RequestHandlerSelectors.basePackage(scanPackage))                .paths(PathSelectors.any())                .build();    }    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个    private ApiInfo apiInfo() {
           return new ApiInfoBuilder()                //页面标题                .title("Demo项目API一览")                //创建人                .contact(new Contact("DavidLei08", "https://github.com/DavidLei08/", "2686849744@qq.com"))                //版本号                .version("1.0")                //描述                .description("API 描述")                .build();    }}

为了方便再不同环境下切换配置，我将swagger的enable和扫描包的配置抽出在ym配置文件中。

当需要禁用swagger时只需要将enable改成false,扫描包名可以根据实际情况修改。

3.controller层使用

@Api 标注当前controller类为api模块

@ApiOperation 标注当前方法为api接口

@ApiResponse 标注当前方法的响应状态和message信息

@ApiParam 标注当前方法的入力参数dto

/** * MqSendController * @author  DavidLei08 */@Api(value = "用户管理类")@RestControllerpublic class MqSendController {
       @Autowired    private MqOperationService mqOperationService;    @ApiOperation(value = "发送mq")    @PostMapping("/sendmq")    @ApiResponse(code = 200, message = "发送mq请求返回的dto")    public BaseResponse sendMq(@ApiParam  @Valid  @RequestBody MqSendRequest request,                               BindingResult result, HttpServletResponse httpResponse){
           BaseResponse response = new BaseResponse();        if(!result.hasErrors()){
               try {
                   mqOperationService.sendMq(request);                response.setHttpStatus("200");                response.setMessage("request is ok");            } catch (Exception e){
                   httpResponse.setStatus(500);                response.setHttpStatus("500");                response.setMessage("mq send failed");            }        } else {
               httpResponse.setStatus(401);            response.setHttpStatus("401");            response.setMessage("request formatter is wrong");        }        return  response;    }}

关于api的文档，可能需要显示，也可能不需要显示，比如error统一处理的controller就不需要对外暴露。

可以将 @Api 替换成 @ApiIgnore 表示api文档忽略当前类。当前类就不会出现再api文档中。

/** * MqSendController * @author  DavidLei08 */@ApiIgnore//@Api(value = "用户管理类")@RestControllerpublic class MqSendController {
       @Autowired    private MqOperationService mqOperationService;    @ApiOperation(value = "发送mq")    @PostMapping("/sendmq")    @ApiResponse(code = 200, message = "发送mq请求返回的dto")    public BaseResponse sendMq(@ApiParam  @Valid  @RequestBody MqSendRequest request,                               BindingResult result, HttpServletResponse httpResponse){
           BaseResponse response = new BaseResponse();        if(!result.hasErrors()){
               try {
                   mqOperationService.sendMq(request);                response.setHttpStatus("200");                response.setMessage("request is ok");            } catch (Exception e){
                   httpResponse.setStatus(500);                response.setHttpStatus("500");                response.setMessage("mq send failed");            }        } else {
               httpResponse.setStatus(401);            response.setHttpStatus("401");            response.setMessage("request formatter is wrong");        }        return  response;    }}

4.输入dto使用

@ApiModel 表示当前类为api输入的model

@ApiModelProperty 表示当前字段为输入字段 -value 是解释 -example 是例子 -required 表示是否是必须字段

/** * MqSendRequest * @author DavidLei08 */@ApiModel(value = "mq发送传入信息model")public class MqSendRequest implements Serializable {
       @NotNull    @NotEmpty    @ApiModelProperty(value = "mq类型-topic/queue", example = "topic",required = true)    private String mqType;    @NotNull    @NotEmpty    @ApiModelProperty(value = "发送目的地名", example = "float_01",required = true)    private String toName;    @NotNull    @NotEmpty    @ApiModelProperty(value = "发送信息内容", example = "test message",required = true)    private String message;    public String getMqType() {
           return mqType;    }    public void setMqType(String mqType) {
           this.mqType = mqType;    }    public String getToName() {
           return toName;    }    public void setToName(String toName) {
           this.toName = toName;    }    public String getMessage() {
           return message;    }    public void setMessage(String message) {
           this.message = message;    }}

swagger插件真心不错

不过代码中会多很多注解，看起来内容有点多，其实无关乎业务，哈哈!!

转载地址：http://whugn.baihongyu.com/

你可能感兴趣的文章