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的注解还有很多,有兴趣的可以搜索一下注解的各种用法,满足我们的日常开发.