swagger搭建与使用

简介

Swagger UI 是目前最流行的 RestFul 接口 API 文档和测试工具，可以直接在官方 demo上进行体验，有疑问可以查看官方文档。

本文主要讲解在springboot下使用swagger

步骤

一、添加依赖

<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>

二、编写配置文件

package com.white.swagger.configs;


import com.google.common.base.Function;
import com.google.common.base.Optional;
import com.google.common.base.Predicate;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.RequestHandler;
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 SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
      
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("后端接口标题")
                .description("后端接口描述")
                .contact(
                        new Contact("flowaters", "www.baidu.com", "flowaters@abeffect.com")
                )
                .version("1.0.0-SNAPSHOT")
                .build();
    }

}

成功访问

编写接口测试

首先修改扫描的包

@Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //.apis(RequestHandlerSelectors.any()) //扫描全部
                .apis(RequestHandlerSelectors.basePackage("com.springboot.swagger")) //扫描指定包
                .paths(PathSelectors.any())
                .build();
    }

创建测试类

package com.springboot.swagger;


import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.HashMap;
import java.util.Map;

@RestController
@RequestMapping("/TestController")
@Api(tags = "测试类")
public class TestController {

    /**
     * get方式提交单个参数
     * @param key
     * @return
     */
    @GetMapping("/getTest")
    @ApiOperation(value = "给我key，我就还你key")
    @ApiImplicitParam(name = "key",value = "快给我key的值",required = true)
    public Map getTest(String key){
        Map map = new HashMap();
        map.put("key",key);
        return map;
    }

    /**
     * post方式提交单个参数
     * @param key
     * @return
     */
    @PostMapping("/postTest")
    @ApiOperation(value = "给我key，我就还你key")
    @ApiImplicitParam(name = "key",value = "快给我key的值",required = true)
    public Map postTest(String key){
        Map map = new HashMap();
        map.put("key",key);
        return map;
    }

    /**
     * post方式提交多个参数
     * @param key
     * @param value
     * @return
     */
    @PostMapping("/postMapTest")
    @ApiOperation(value = "给我键值对，我就还你键值对")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "key",value = "快给我key的值",required = true)
            ,@ApiImplicitParam(name = "value",value = "快给我value的值",required = true)
    })
    public Map postMapTest(String key,String value){
        Map map = new HashMap();
        map.put("key",key);
        map.put("value",value);
        return map;
    }

    @PostMapping("/postBeanTest")
    @ApiOperation(value = "给我键值对，我就还你一个bean")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "key",value = "快给我key的值",required = true)
            ,@ApiImplicitParam(name = "value",value = "快给我value的值",required = true)
    })
    public TestBean postBeanTest(String key,String value){
        TestBean bean = new TestBean(key,value);
        return bean;
    }

}

测试bean

package com.springboot.swagger;


import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("测试bean")
public class TestBean {

    @ApiModelProperty(value = "我要键")
    private String key;

    @ApiModelProperty(value = "我要值")
    private String value;

    public TestBean(String key, String value) {
        this.key = key;
        this.value = value;
    }

    public String getKey() {
        return key;
    }

    public void setKey(String key) {
        this.key = key;
    }

    public String getValue() {
        return value;
    }

    public void setValue(String value) {
        this.value = value;
    }
}

成功访问

swagger配置多包扫描

如何配置多包扫描请查看我另外一篇文章

源码下载

源码下载