swagger生成文檔初步使用

　　在大部分狀況下,公司都會要求提供詳細的接口文檔,對於開發來講,文檔有時候在趕進度的狀況下,也是一件頭疼的事.而swagger的自動生成文檔功能,就能夠幫助咱們減小工做量,對於文檔的修改也能夠在代碼中隨時修改,對於項目比較急的項目也不失爲一種好的解決方案.

　　對於springboot項目,須要引入相關依賴

　　　　

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

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

    <dependency>
      <groupId>com.github.xiaoymin</groupId>
      <artifactId>swagger-bootstrap-ui</artifactId>
      <version>1.8.1</version>
    </dependency>

　　相關依賴爲咱們提供了可視化文檔界面,而且支持文檔的導出.

　　咱們也須要加入相關的配置,spring boot通常推薦使用註解配置的形式,不推薦使用xml形式,因此在此添加config配置類.

@Configuration
public class SwaggerConfig implements WebMvcConfigurer {
  public void setSwagger_is_enable(String swagger_is_enable){
      enable=true;  //此處爲控制文檔主頁顯示的開關 能夠經過配置傳入動態控制
     
    }
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .enable(enable)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.jzfq.swagger"))
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("springboot利用swagger構建api文檔")
            .description("簡單優雅的restfun風格，http://blog.csdn.net/saytime")
            .version("1.0")
            .build();
    }

在此配置類裏面,咱們增長了ui界面的一些主頁信息,在Bean的配置中,須要添加文檔註解的掃描路徑,這樣咱們的註解纔可以被掃描解析到

在spring boot的啓動類上開啓swagger的自動配置 使用註解@EnableSwagger2

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
@SpringBootApplication
public class Swagger01Application {

  public static void main(String[] args) {
    SpringApplication.run(Swagger01Application.class, args);
  }
}

 

由此spring boot就集成了swagger2.接下來咱們能夠一個demo測試接口文檔的生成.

咱們的參數可能直接使用vo來接收,咱們能夠建立一個User實體類

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;

@ApiModel(description = "用戶實體類")
public class User implements Serializable {
    @ApiModelProperty(value ="姓名",allowableValues = "張三,李四,王五")
    private String name;
    @ApiModelProperty(value ="性別",allowableValues = "男,女,未知")
    private String sex;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getSex() {
        return sex;
    }

    public void setSex(String sex) {
        this.sex = sex;
    }
}

 接下來建立一個controller層 經過post man進行調用

import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class SwaggerTestController {


    @ApiOperation(value = "測試生成Swagger", notes = "測試生成Swagger", tags = "swagger模塊")
    @ApiImplicitParams(
        @ApiImplicitParam(name = "age", value = "年齡", paramType = "body", dataType = "Integer", required = true)
    )
    @ApiResponses(
        @ApiResponse(code = 400, message = "請求參數沒填好")
    )
    @PostMapping("/test")
    public void test( User user){
        System.out.println("Spring boot 集成 Swagger2");
    }
}

最後一步,咱們經過訪問 http://localhost:8080/doc.html地址,咱們就能夠看到這樣一個界面,由此就集成了一個簡單的swagger.對於swagger的註解還有不少,有興趣的能夠搜索一下註解的各類用法,知足咱們的平常開發.