swagger生成文档初步使用

　　在大部分情况下,公司都会要求提供详细的接口文档,对于开发来说,文档有时候在赶进度的情况下,也是一件头疼的事.而swagger的自动生成文档功能,就可以帮助我们减少工作量,对于文档的修改也可以在代码中随时修改,对于项目比较急的项目也不失为一种好的解决方案.

　　对于springboot项目,需要引入相关依赖

    <dependency>

      <groupId>io.springfox</groupId>

      <artifactId>springfox-swagger2</artifactId>

      <version>2.7.</version>

    </dependency>

    <dependency>

      <groupId>io.springfox</groupId>

      <artifactId>springfox-swagger-ui</artifactId>

      <version>2.7.</version>

    </dependency>

    <dependency>

      <groupId>com.github.xiaoymin</groupId>

      <artifactId>swagger-bootstrap-ui</artifactId>

      <version>1.8.</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 = , message = "请求参数没填好")

    )

    @PostMapping("/test")

    public void test( User user){

        System.out.println("Spring boot 集成 Swagger2");

    }

}

最后一步,我们通过访问 http://localhost:8080/doc.html地址,我们就可以看到这样一个界面,由此就集成了一个简单的swagger.对于swagger的注解还有很多,有兴趣的可以搜索一下注解的各种用法,满足我们的日常开发.

巴特西

swagger生成文档初步使用

最新文章

热门文章