SpringBoot-整合Swagger2

Posted 2020-11-23 大愿、如愿

swagger2是一个用于生成、并能直接调用的可是话restful风格的服务

下面贴出springboot整合swagger2代码

一、maven依赖

这里使用的spring-boot版本是2.1.1.RELEASE，swagger2使用的是2.9.2，我一开始用的springboot1.5.6.RELEASE，swagger从2.4到2.9.2都用了，结果又很多jar包冲突，springboot换成了2.*版本依旧，依然有jar冲突，无奈，只能把冲突的依赖找出来，有具体报错信息，把他exclude掉就行，而且idea的maven-helper插件帮助也蛮大

<!-- swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
    <exclusions>
        <exclusion>
            <artifactId>spring-context</artifactId>
            <groupId>org.springframework</groupId>
        </exclusion>
        <exclusion>
            <artifactId>spring-beans</artifactId>
            <groupId>org.springframework</groupId>
        </exclusion>
        <exclusion>
            <artifactId>spring-aop</artifactId>
            <groupId>org.springframework</groupId>
        </exclusion>
    </exclusions>
</dependency>
<!-- swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

二、swagger2配置

package com.hy.other.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {


    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 生成api的包路径（一般是我们controller包的路径）
                .apis(RequestHandlerSelectors.basePackage("com.hy.other.controller"))
                .paths(PathSelectors.any())
                .build();
    }


    // swagger ui 页面里面的一些信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 页面标题
                .title("spring boot swagger")
                // 创建人
                .contact(new Contact("hy", "https://www.cnblogs.com/xhy-shine", ""))
                // 版本号
                .version("1.0")
                // 描述
                .description("API接口文档")
                .build();
    }
}

注意：@EnableSwagger2一定要加上，不然会无法访问swagger的ui界面，会报如下错误

三、代码（主要是swagger2的注解）

 注解有挺多的，比较常用的就是@Api、@ApiOperation、@ApiImplicitParam、@ApiModel、@ApiModelProperty

@Api：包括下面的所有接口，有点类注释的意思

@ApiOperation：给接口增加说明

@ApiImplicitParams、@ApiImplicitParam：给接口参数添加说明

@ApiModel：描述对象类型的请求参数

@ApiModelProperty：描述对象的属性

注意：@ApiModelProperty注解的参数说明

　　paramType：指定参数放在哪个地方（header：request header中，使用@RequestHeader获取；query：使用@RequestParam获取；path：使用@PathVariable获取；body、form两者不常用）可参考：https://swagger.io/docs/specification/describing-parameters/

　　name：参数名

　　dataType：参数类型

　　required：是否必须

　　value：参数的意思

　　defaultValue：默认值

package com.hy.other.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.amqp.rabbit.core.RabbitTemplate;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@Api(description = "MQ接口")
@RestController
@RequestMapping("/messageQueue")
public class MessageQueueController {

    @Value("${rabbitmq.exchangeName}")
    private String exchangeName;
    @Value("${rabbitmq.queueName}")
    private String queueName;
    @Value("${rabbitmq.routeKey}")
    private String routeKey;

    @Autowired
    private RabbitTemplate rabbitTemplate;


    @ApiOperation(value = "send message to spin", notes = "发送消息到spin")
    @ApiImplicitParam(name = "message", value = "消息内容", required = true, paramType = "query")
    @RequestMapping("/sendWso2ToSpin")
    public String sendWso2ToSpin(@RequestParam("message") String message) {
        rabbitTemplate.convertAndSend(exchangeName, routeKey, message);
        return message;
    }

}

 

访问地址你的项目根路径加上swagger-ui.html就行

 

 

1、swagger会根据@RequestParam、@RequestBody注解来决定用form提交还是application/json格式（上图出现Parameter content type为application/json是因为我把请求参数前的注解改成了@RequestBody）

2、会根据@RequestMapping、@PostMapping、@GetMapping等注解生成对应的请求，如上，我写的@RequestMapping，他把所有请求格式都生成了

3、如果接收的是对象，可以使用@ApiModel结合@ApiModelProperty