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的注解還有很多,有興趣的可以搜索一下注解的各種用法,滿足我們的日常開發.