SpringBoot-整合Swagger2

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界面,会报如下错误

SpringBoot-整合Swagger2

三、代码(主要是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就行

SpringBoot-整合Swagger2

 SpringBoot-整合Swagger2

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

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

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

相关推荐