SpringBoot+Swagger2

SpringBoot+Swagger2

Swagger的出现就是为了方便进行测试后台的restful形式的接口，实现动态的更新，当我们在后台的接口修改了后，它可以实现自动的更新

---

① pom.xml中添加依赖

<!-- 获取API -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>

<!-- 获取UI界面 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
</dependency>

<!-- 测试数据以JSON返回(非必须) -->
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.7.5</version>
</dependency>

② 添加配置类

@Configuration
public class SwaggerConfig extends WebMvcConfigurationSupport {
    <!-- 获取swagger-ui.html页面 -->
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    <!-- 接口概述(名称、介绍、版本) -->
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API接口文档")
                .description("用户信息管理")
                .version("1.0.0")
                .build();
    }

    <!-- 调用接口 -->
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("控制器类路径"))
                .paths(PathSelectors.any())
                .build();
    }

③ 导入配置类

<!-- 配置总类中导入Swagger -->
@Configurable
@Import({SwaggerConfig.class})
public class ApplicationConfig {}

④ 编写Controller

@RestController
@RequestMapping("/user")
@Api("用户信息管理")
public class UserApi {
    @Resource
    private UserMapper userMapper;

    @RequestMapping(value = "/id", method = RequestMethod.POST)
    @ApiOperation(value = "获取用户信息", notes = "通过用户ID获取用户信息")
    public Object getUserById(@ApiParam(value = "用户Id", required = true) Integer id) {
        return userrMapper.geUserById(id);
    }
}

⑤ 启动Swagger

<!-- 启动类中开启Swagger -->
@SpringBootApplication
@Import(ApplicationConfig.class)
@EnableSwagger2
public class ApplicationStart {
    public static void main(String[] args) {
        SpringApplication.run(ApplicationStart.class, args);
    }
}

⑥ 启动SpringBoot项目，访问 localhost:端口号/上下文路径/swagger-ui.html

---

Swagger常用注解

Name	Description
@Api	将类标记为Swagger资源
@ApiImpl定量Param	表示API操作中的单个参数
@ApiImplilia Params	一个包装器，用于允许多个ApiImpl时Param对象的列表
@ApiModel	提供有关Swagger模型的其他信息
@ApiModelProperty	添加和操作模型属性的数据
@ApiOperation	描述针对特定路径的操作或通常是HTTP方法
@ApiParam	为操作参数添加额外的元数据
@ApiResponse	描述操作的可能响应
@ApiResponses	允许多个ApiResponse对象列表的包装器
@授权	声明要在资源或操作上使用的授权方案
@AuthorizationScope	描述OAuth2授权范围

详见 [https://github.com/swagger-api/swagger-core/wiki/Annotations#operation-declaration]