Springboot集成Swagger2 ,基本使用

关于swagger的简介不在多聊,直接上集成教程.

1.在pom.xml中添加swagger 所需Maven依赖

<!--maven地址 https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--maven地址 https://mvnrepository.com/artifact/io.springfox/springfox-swagger2-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

如果导入过程中出现错误,请参照上一个帖子进行解决.

2.添加Swagger配置类

首先创建SwaggerConfig.java

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
//开启swagger
@EnableSwagger2
public class Swagger2Configuration {

    //定义api接口包的扫描路径,扫描指定controller
    private static  final String SWAGGER_SCAN_PACKAGE = "com.czxy.changgou3.controller";
    //设置生成文档的版本信息
    private static final String API_VERSION = "1.0.0";

    @Bean
    public Docket createApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                //该方法会返回一个ApiSelectorBuild对象实例
                .select()
                //我们通过该实例设置暴露哪些接口给swagger展示
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_PACKAGE))
                //根据上面设置的包扫描路径,把此包下那些请求加入到文档中
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * @return 创建该api的基本信息
     */
    private ApiInfo apiInfo(){
        //使用建造者模式创建
        return new ApiInfoBuilder()
                //设置文档的标题
                .title("畅购前台")
                //设置文档的描述信息
                .description("畅购前台API接口文档")
                //设置文档的版本信息
                .version(API_VERSION)
                //设置文档的许可证信息
                .termsOfServiceUrl("http://localhost:10010/v3")
                //构建ApiInfo对象
                .build();
    }


}

3.在controller中完成API文档接口编写

@Api(tags = {"畅购前台用户接口"})
@RestController
@RequestMapping("/user")
public class UserController {

    @Resource
    UserService userService;


    @PostMapping("/checkusername")
    @ApiOperation(value = "校验用户名",notes = "用来校验用户名",produces = "application/json")
    @ApiImplicitParam(name = "user",value = "用户",paramType = "body",required = true,dataType = "User")
    public BaseResult checkusername(@RequestBody User user){
       User user1 = userService.checkusername(user);

       if (user1==null)
           return  BaseResult.ok("用户名可用");
           return  BaseResult.error("用户名不可用");
    }
}

以检验用户名的接口为例.
@Api在接口类上声明,描述该controller的整体作用

@ApiOperation则修饰方法,value在文档中充当该接口的title,notes则为改接口的作用说明,produces 则对请求体的文本类型进行描述.

@ApiImplicitParam则是对单个请求参数进行描述,name为该参数名
,value则对这个字段进行描述,paramType 是对参数类型的说明,dataType则是对数据类型的说明.

多个请求参数请使用@ApiImplicitParams

4.启动应用,访问校验

在项目成功启动后,访问:
http://ip:port/swgger-ui.html

如图所示,能够成功访问到,并且我们的参数配置已经生效.