springboot整合swagger2 入门篇（适合初学者）

spring boot 整合 swagger2
spring cloud 整合 swagger2

1. pom.xml 引入maven swagger2 jar包依赖

      <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>

2. 项目中新建配置 swagger2 文件类 SwaggerConfig

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

/**
 * Swagger2
 * http://localhost:8100/swagger-ui.html
 */
// 被SpringBoot扫描到，通知 spring 这是一个配置类
@Configuration
// 引入 Swagger2
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                // 方法需要有ApiOperation注解才能生存接口文档
                // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 默认 api所在的package 都生成
                .apis(RequestHandlerSelectors.basePackage("dome2.springcloud.domeparentrestservice1.api"))
                // 页面风格
                .paths(PathSelectors.any())
                // 运行并初始化相关内容
                .build().apiInfo(
                        new ApiInfoBuilder()
                                .title("Swagger2 接口测试")
                                .version("2.0")
                                .build()
                );
    }
}

3. 重启项目测试 /swagger-ui.html

我的端口是 8100
所以我的测试地址为 http://localhost:8100/swagger-ui.html

4. swagger2 api 接口请求参数，api接口标题 使用说明

示例如下：

    @ApiOperation(value = "提交订单")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "orderId1", value = "订单Id", required = true), // orderId1
            @ApiImplicitParam(name = "orderId2", value = "订单Id2", required = true, dataType = "String", paramType = "path"), // orderId2
            @ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User") // user
    })
    @RequestMapping(value = "add/order/{orderId2}", method = RequestMethod.POST)
    public String addOrder(
            @RequestParam String orderId1,
            @PathVariable String orderId2,
            @RequestBody User user) {
        return "add/order";
    }

   // 接口备注
   @ApiOperation(value = "提交订单")

   // 参数说明
   @ApiImplicitParams({
           @ApiImplicitParam(name = "orderId1", value = "订单Id", required = true), // orderId1
           @ApiImplicitParam(name = "orderId2", value = "订单Id2", required = true, dataType = "String", paramType = "path"), // orderId2
           @ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User") // user
   })

效果：