Swagger2簡單使用教程

1、簡介

Swagger是為了解決企業中接口（api）中定義統一標准規范的文檔生成工具。很多采用前后端分離的模式，前端只負責調用接口，進行渲染，前端和后端的唯一聯系，變成了API接口。因此，API文檔變得越來越重要。swagger是一個方便我們更好的編寫API文檔的框架，而且swagger可以模擬http請求調用。

2、常用注解與示例

@Api（）用於類：表示標識這個類是swagger的資源

@Api("用於類")
 @Controller
 public class swaggerTest(){
 }

@ApiOperation（）用於方法：表示一個http請求的操作

@Api("ApiOperation測試")
@Controller
public class swaggerTest(){
    @ApiOperation(value = "apiOperationTest", notes = "apiOperation測試")
    public void apiOperationSwaggerTest(){
    }
}

@ApiParam（）：用於方法，參數，字段說明：表示對參數的添加元數據（說明或是否必填等）

@Api("ApiParam測試")
@Controller
public class swaggerTest(){
    @ApiOperation(value = "apiOperationTest", notes = "apiOperation測試")
    public void apiOperationTest(@ApiParam(name = "id", value = "1", required = true) Integer id){
    }
}

@ApiModel（）用於類：表示對類進行說明，用於參數用實體類接收

@ApiModel(description = "實體類", value = "實體類")
public class City implements Serializable {
   
}

@ApiModelProperty（）用於方法，字段：表示對model屬性的說明或者是數據操作更改

@ApiModel(description = "實體類", value = "實體類")
public class City implements Serializable {
    @ApiModelProperty(name = "id", value = "編號", required = false, exmaple = "1")
    private int id;
}

@ApiIgnore（）用於類，方法，方法參數：表示這個方法或者類被忽略

@ApiIgnore
@Api(tags = {"Xxx控制類"})
@RestController
@RequestMapping("/xxx")
public class XxxController {
	
}

@ApiImplicitParam（）用於方法：表示單獨的請求參數

@ApiImplicitParams（）用於方法，包含多個@ApiImplicitParam

@Api("測試1")
  @Controller
  public class swaggerTest(){
      @ApiOperation(value = "apiOperationTest", notes = "apiOperation測試")
      @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "id", required = true, dataType = "Integer", paramType = "query"),
                        @ApiImplicitParam(name = "name", value = "name", required = true, dataType = "String", paramType = "query")
    })
      public void apiOperationSwaggerTest(Integer id, String name){
      }
  }

3、使用步驟

maven導入依賴

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

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>

創建配置類

給出一些基礎配置

@Configuration
@EnableSwagger2 //開啟Swagger2
public class Swagger2 {

    //是否開啟swagger，正式環境一般是需要關閉的，可根據springboot的多環境配置進行設置
    @Value(value = "${swagger.enabled}")
    Boolean swaggerEnabled;
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxxxxx.xxxxx")) //你的項目基礎包名
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("標題")
                .description("api接口文檔")
                .version("1.0") //版本
                .build();
    }

}

SpringBoot 配置文件開啟swagger

application-dev.yml文件

swagger:
    enabled: true

注意導包不要導錯

import org.springframework.beans.factory.annotation.Value;
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;

實體類demo

@Entity
@Table(name = "city")
public class City implements Serializable {
    private static final long serialVersionUID = 1L;
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    @Column(name = "ID")
    @Getter
    @Setter
    private int ID;
    @Column(name = "Name")
    @ApiModelProperty(value = "城市名字", dataType = "String", name = "name", example = "Kabul")
    @Getter
    @Setter
    private String Name;

代碼中的@Getter@Setter 注解是使用 lombok代替get與set方法，使用方法參考另一篇

service與dao略過看controller的寫法

 @ApiOperation(value="按id查詢城市信息")
    @ResponseBody
    @GetMapping("/queryCityList")
    public String queryCityList(@RequestParam("id") int id)  {
        List<City> queryCityList = cityService.queryCityList(id);
        String jsonString = JSON.toJSONString(queryCityList);
        return  jsonString;
    }