这不做基本介绍了,新手只需要知道是一个接口文档规范,按照它的规范(注解形式)能自动生成web形式接口文档,通过url都前后端都可以访问,方便数据交互就可以了,重点在于使用

spring boot 中swagger2的依赖

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

spring boot已经整合了swagger,就是springfox,其作用就是生成接口文档,简化开发.
还有一个依赖是

<dependency>
			<groupId>com.mangofactory</groupId>
			<artifactId>swagger-springmvc</artifactId>
			<version>0.9.5</version>
		</dependency>

springfox就是由swagger-spingmvc发展而来,前者自然比后者更强大更适用.

在这里只是实用的例子,基本开发够用,想深入,去官网

springfox官网链接

导入依赖后,首先要做的就是写一个配置类(复制粘贴下方代码,日常开发基本可以满足,要求比较高的话可查官网增加配置)

import io.swagger.annotations.ApiOperation;
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;
import java.util.HashSet;
import java.util.Set;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    @Bean
    public Docket createRestApi() {
        Set<String> producesList = new HashSet<>();
        producesList.add("application/json");
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .produces(producesList)
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }
    
    //文档信息说明和个人信息配置
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("我的swagger")
                .description("我的的描述")
                .contact(new Contact("我的邮箱", "", "xxxxxxxx@163.com"))
                .version("1.0")
                .build();
    }
}

写完配置类后,启动application就可以访问swagger web页面了,
swagger web页面地址(接口文档):**http://localhost:8080/swagger-ui.html**
我们的接口文档的雏形也就出来了 apiInfo()方法中定义的内容,可对比下图

接口文档雏形已经有了,剩下的就是接口实际对接参数了.

@Api(value = "Api value啊", tags = {"Api tags啊"})
@RestController
@RequestMapping("/account")
public class AccountController {

}

上方是一个controller
@Api注解是swagger注解,作用就是对于当前的controller做一个说明

下方是一个controller中的一个方法

@ApiOperation(value = "ApiOperation Value啊", notes = "ApiOperation Note啊")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户编号", required = true,dataType = "long"),
            @ApiImplicitParam(name = "name", value = "用户名", required = false)
    })
    @RequestMapping(value = "/swagger", method = RequestMethod.GET)
    public String swaggerTest(@RequestParam("id") Long id, @RequestParam("name") String name) {
        return name + ":" + id;
    }

@ApiOperation 是非常重要的一个注解,作用于方法上,用来做方法的说明
比如@ApiOperation(values = “获取用户信息”) 前端很容易就可以知道,获取用户信息要调用这个接口.其中的notes是注意事项,也可以理解成描述,可以将请求参数等信息直接用文字写到里面,虽然不正式,但是如果能说明白,也可以不需要再用
@ApiImplicitParam @ApiImplicitParams @ApiParam等注解再对参数进行说明,偷懒时候可以这么干.

@ApiImplicitParams相当于 @ApiImplicitParam集合
@ApiImplicitParam是对入参进行说明,但是只是对单个参数说明,比如long id
就用@ApiImplicitParam(name = “id”,value=“用户编号”, required = true,dataType = “long”) name 必须等于参数名,value是参数说明.还有一个参数是String name 就再用一个注解去说明.但是如果是一个自动封装的Bean对象,比如Test test 这个注解就不能说明出Test对象中每一个属性了,也就是@ApiImplicitParam注解只能说明当前对象,但是对向前对象内部结构无法说明,后面会讲解.

@ApiParam注解作用基本等同于@ApiImplicitParam

@ApiOperation(value = "swagger啊", notes = "swagger1注意事项")
    @RequestMapping(value = "/swagger1", method = RequestMethod.GET)
    public String swaggerTest1(@RequestParam("id")  @ApiParam(name="用户编号",value="用户号编号说明",required=true)Long id,
                               @RequestParam("name")  @ApiParam(name="用户名字",value="用户名字说明",required=true) String name) {
        return name + ":" + id;
    }
123456

它作用在参数上,也是对参数的说明,@ApiParam中name可以不是参数名,value是对参数的描述,所以选择用@ApiParam还是@ApiImplicitParam 可以自己决定,不过我比较推荐,基本数据类型用@ApiImplicitParam, Bean类型用@ApiParam.

最后一个方法

@ApiOperation(value = "swagger2啊", notes = "swagger2注意事项")
    @RequestMapping(value = "/swagger2", method = RequestMethod.POST)
    public String swaggerTest2(@RequestBody @ApiParam(name="用户对象",value="用户对象说明",required=true) Test test) {
        return test.getString2() + ":" + test.getString1();
    }

这样子只能对于test这个对象进行说明,但是内部属性,没有办法说明,因为我们是json自动转对象,所以有必要说明下test中每个字段,前端也好传参,要说明自定义对象,需要用@ApiModel 和@ApiModelProperty 注解

@ApiModel(value="test对象",description="test测试")
public class Test {
   @ApiModelProperty(
           name = "string1",
           value = "第一个string",
           dataType = "String",
           example = "string1example",
           required = true)
   private String string1;

   @ApiModelProperty(
           name = "string2",
           value = "第二个string",
           dataType = "String",
           example = "string2example",
           required = false
   )
   private String string2;

///getter setter toString

}

@ApiModel注解作用于类上,是对类的说明,@ApiModelProperty是对属性的说明

以上就是springfox(swagger)的基本使用,开发中用的最多的几个注解已经说明了,至于其他的注解我现在基本不用,所以不再说明.要学习springfox,就多写几个接口,用几次注解,熟悉一下web 页面,很快就可以学会~