springboot 整合swagger2

版权声明：本文为博主原创文章，未经博主允许不得转载。 https://blog.csdn.net/zc_ad/article/details/83302937

相信很多人都用过postman，使用postman其实可以很简便的进行接口调试，但是呢，每次还要写url，以及要添加参数名字(很容易写错)。所以啊，swagger2优势就体现出来了，它只需要添加少量注解即可在项目下调试接口，并且可以根据项目是否是测试还是生产环境，可以显示或禁止页面接口调试，介绍就到这里，开始写整合部分。

一.maven添加依赖

此处使用的是2.7.0版本，下面的ui二选一即可，springfox-swagger-ui是官方提供的UI界面（本人一直使用的是这个），swagger-bootstrap-ui是基于左右菜单风格，GitHub项目地址:https://github.com/xiaoymin/Swagger-Bootstrap-UI

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.7.0</version>
</dependency>
<!--springfox-swagger-ui       http://localhost:8010/swagger-ui.html-->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.7.0</version>
</dependency>
<!--bootstap-ui               http://localhost:8010/doc.html-->
<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>swagger-bootstrap-ui</artifactId>
	<version>1.6</version>
</dependency>

二.swagger2配置文件

本人喜欢将swagger2一些参数写到配置文件中，方便以后修改，也可以将其写死。在application.yml中添加以下配置。enable为true是表示在swagger-ui.html中显示接口。

swagger:
  enable: true
  info:
    version: 0.1
    title: 兮川项目的接口
    description: 薛定谔的猫，你不去验证，就无法知道真假
    user_name: 兮川
    url:
    email:

在config配置中，apiInfos()方法是添加通用属性的，如邮箱、版本、描述等。headerInfos()方法是添加头参数，如果每个接口头中没有通用参数的话，可以将其删除，顺便将每一个接口扫描中将.globalOperationParameters(headerInfos())也删除掉。

每一个接口扫描中,.apiInfo(apiInfo())表示添加通用属性。.enable(enableSwagger)表示是否在页面显示此接口列表。.groupName("访客接口列表")表示接口列表的名字(名字必须唯一)。.apis(RequestHandlerSelectors.basePackage("com.xichuan.visit.controller"))表示扫描一个package下的所有接口。.globalOperationParameters(headerInfos())表示添加头信息。

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Value("${swagger.enable}")
    private boolean enableSwagger;

    @Value("${swagger.info.version}")
    private String version;

    @Value("${swagger.info.title}")
    private String title;

    @Value("${swagger.info.description}")
    private String description;

    @Value("${swagger.info.user_name}")
    private String userName;

    @Value("${swagger.info.url}")
    private String url;

    @Value("${swagger.info.email}")
    private String email;


    /**访客接口*/
    @Bean
    public Docket visitApis() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(enableSwagger)
                .groupName("访客接口列表")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xichuan.visit.controller"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(headerInfos());
    }

    /**通用接口*/
    @Bean
    public Docket generalApis() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(enableSwagger)
                .groupName("通用接口列表")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xichuan.general.controller"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(headerInfos());
    }

    private List<Parameter> headerInfos(){
        //添加head参数
        List<Parameter> headerParams = new ArrayList<>();
        ParameterBuilder schoolIdParams = new ParameterBuilder();
        schoolIdParams.name("school_id").description("school_id").modelRef(new ModelRef("String")).parameterType("header").defaultValue("").required(false).build();
        ParameterBuilder devMacParams = new ParameterBuilder();
        devMacParams.name("dev_mac").description("dev_mac").modelRef(new ModelRef("String")).parameterType("header").defaultValue("00:08:22:B6:10:04").required(false).build();
        headerParams.add(schoolIdParams.build());
        headerParams.add(devMacParams.build());
        return headerParams;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .contact(new Contact(userName,url,email))
                .version(version)
                .build();
    }
}

三.在代码中运用

在代码中运用其实很简单，主要使用@Api、@ApiOperation、@ApiIgnore三个注解就可以完成平时开发工作。先上一下代码块。

@RestController
@RequestMapping("/xichuan/RSA")
@Api(tags = "数据RSA AES加密传输")
public class RSAController {

    @Autowired
    RSAService rsaService;

    @GetMapping("/key")
    @ApiOperation("通过平台code获取公钥")
    @ApiImplicitParam(name = "platform_code",value = "平台Code",defaultValue ="message_send" ,required = true,dataType = "String",paramType = "query")
    public Response getPublicKeyByCode(@RequestParam("platform_code")String platformCode){
        return rsaService.getPublicKeyByCode(platformCode);
    }

    @PostMapping("/message")
    @ApiOperation("通过AES加密的code pwd,RSA加密的key,获取用户详细AES加密信息")
    public Response getUserMessageDetail(@RequestBody Message message)throws Exception{
        return rsaService.getUserMessageDetail(message);
    }

}

public class Message {

    @ApiModelProperty(example = "message_send")
    @JsonProperty("platform_code")
    public String platformCode;

    @ApiModelProperty(example = "123www")
    @JsonProperty("encrypt_key")
    public String encryptKey;

    @ApiModelProperty(example = "456ccd")
    public String data;

    public Message(){}

    public Message(String platformCode,String encryptKey,String data){
        this.platformCode = platformCode;
        this.encryptKey = encryptKey;
        this.data = data;
    }
}

相信看完实例，你会大致理解这些注解的作用了。

@Api(tags = " ")放在controller类上面，表示此类接口列表的名字；

@ApiOperation(value=" "，note=" ")，写在方法上，表示此方法的作用，其中value表示此方法的名字，note可以写自己对此方法的理解以及描述等

@ApiImplicitParam(name = "",value = "",defaultValue ="" ,required = true,dataType = "",paramType = "")，此注解写在方法上，（本人不怎么使用）。name表示参数名字。value表示参数名称。defaultValue表示默认值。requared表示此参数是否必须有值。dataType表示参数的类型。paramType 表示参数的类型，header-->请求参数的获取在@RequestHeader中；query-->请求参数的获取在@RequestParam中；path（用于restful接口）-->请求参数的获取在@PathVariable中；body（不常用）；form（不常用）

@ApiImplicitParams放在方法上，指的是一组参数的说明

@ApiIgnore：写方法上，表示此接口在swagger不显示，写在类上，表示此类中的接口在swagger全部不显示。

在@RequestBody参数中，如果想指定每个字段的默认值，需要使用@ApiModelProperty注解。@JsonProperty("encrypt_key")是为了在调用时，将其调用的参数格式写为下划线格式。

添加完这些配置中，运行你的项目，然后访问http://localhost:8080/swagger-ui.html(此处只是个例子，注意端口号要与你的项目一致)即可使用swagger2来调用你的接口了。