SpringBoot 整合 Swagger 生成API

一、前言

现如今网站开发都是前后端分离的方式，而前后端唯一的联系就是通过API接口。可想而知，编写一个API是多么重要。那么怎么写API文档呢？我要用到的就是Swagger

二、什么是Swagger?

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。就是让你可以更好书写API文档框架。相比于手写以文件保存或者一些编写软件，它更具有实时性，可以更简单迅速地写好美观的API。

三、如何把Swagger集成在项目中？

1. 将下面的依赖添加到pom.xml文件中

• springfox=swagger2组件帮我们自动生成描述API的json文件。
• springfox-swagger-ui组件将这个json文件解析出来，更好的呈现出来。

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

2. 添加Swagger的配置类

• 通过 basePackage来指定Swagger扫描的类的范围。
• paths()是通过路径来指定Swagger扫描的类的范围，这里对所有路径监控。

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.test.controller"))  //添加ApiOperiation注解的被扫描
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("swagger和springBoot整合")
                .description("swagger的API文档")
                .version("1.0")
                .build();
    }
}

3. 在Controller类上添加@API注解，标识该类是Swagger的资源。vale-字段说明。

• 只要在方法上添加@ApiOperation注解，表示一个http请求的操作。value-字段说明，notes-注释说明

@Api("list")
@ApiOperation(value = "商品列表",notes = "获取商品列表")
@RequestMapping("/to_list")
public String list(Model model, MiaoshaUser user){
    model.addAttribute("user",user);
        //查询商品列表
    List<GoodsVo> goodsList = goodsService.listGoodsVo();
    model.addAttribute("goodsList",goodsList);
    return "goods_list";
}

4. 在启动类上添加@EnableSwagger2注解，运行。

@SpringBootApplication
@EnableSwagger2
public class App {
    public static void main( String[] args ) throws Exception {
        SpringApplication.run(App.class,args);
    }
}

5. 打开浏览器，访问http://localhost:8080/swagger-ui.html，展示结果。