Swagger2整合springBoot,自动生成API接口文档

Swagger2整合springBoot

首先导入jar包

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

注意：我一开始导入的是2.7.0jar包，访问swagger页面，图片加载不出来。后面找了半天没找到原因，应该是jar包里面的静态资源损坏了，索性换了2.8.0就好了

新建config

@Configuration
@EnableSwagger2
public class SwaggerConfiguration extends WebMvcConfigurationSupport {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.mochu.ferp.erp.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("ERP接口文档说明")
                //创建人
                .contact(new Contact("吴彦祖","","[email protected]"))
                //版本号
                .version("1.0")
                //描述
                .description("联系人")
                .build();
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")   
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }
}

注意 ：很多人就是没有添加静态资源映射，重写WebMvcConfigurationSupport 类的addResourceHandlers 方法，指定静态资源的位置。

启动项目，访问Swagger2页面

开始 ：访问 http://localhost:8080/swagger-ui.html ，端口号即为自己项目的端口

config的 apiInfo 方法对界面上内容进行设置，这些没多大用，大家知道就好。

给类加上注解，实现自动生成API

常用注解：

• @Api()用于类；
  表示标识这个类是swagger的资源
• @ApiOperation()用于方法；
  表示一个http请求的操作
• @ApiParam()用于方法，参数，字段说明；
  表示对参数的添加元数据（说明或是否必填等）
• @ApiModel()用于类
  表示对类进行说明，用于参数用实体类接收
• @ApiModelProperty()用于方法，字段
  表示对model属性的说明或者数据操作更改
• @ApiIgnore()用于类，方法，方法参数
  表示这个方法或者类被忽略
• @ApiImplicitParam() 用于方法
  表示单独的请求参数
• @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

---

@ApiImplicitParam 的 paramType属性注解解释

属性	取值	作用
paramType		对应请求参数类型
	path	以地址的形式提交数据
	query	直接跟参数完成自动映射赋值
	body	参数在请求体里面
	form	以form表单的形式提交 仅支持POST
	header	参数在request headers 里边提交

//控制层上注解
@RestController
@RequestMapping("/archives")
@Api(tags="档案管理类")
public class ArchivesController {
    private final Logger logger = LoggerFactory.getLogger(this.getClass());

    @GetMapping("/abc")
    @ApiOperation(value="获取订单", notes="提交一组识别的标签id，返回生成的订单详情")
    public ResultVO get(@ApiParam(name="id",value="优惠券对象") @RequestParam(name = "id") String id){
       return ResultVOUtil.success();
   }

    @PostMapping("/edf")
    @ApiOperation(value="修改订单", notes="提交一组识别的标签id，返回生成的订单详情")
    public ResultVO post(@ApiParam(name="coupon",value="优惠券对象") @RequestBody Coupon coupon){
       return ResultVOUtil.success(coupon);
    }

    @ApiImplicitParams({
            @ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
            @ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
    @PostMapping("/hig")
    public ResultVO post(@ApiParam(hidden = true)@RequestBody Order order){
        return ResultVOUtil.success(order);
   }
}


//模型表上注解
@Data  //lombok插件的注解，自动生成get,set方法
@ApiModel(value="ResultVO",description = "http请求返回的最外层对象")
public class ResultVO<T> {

    /** 错误码. */
    @ApiModelProperty(value="返回码",name="code")
    private Integer code;

    /** 提示信息. */
    @ApiModelProperty(value="提示信息",name="msg")
    private String msg;

    /** 具体内容. */
    @ApiModelProperty(value="具体内容",name="data")
    private T data;
}

页面显示

注意 ：如果方法采用@RequesMapping 注解必须指定方法类型，GET,POST等，否则出现多条API记录。

这是swagger自动生成的API文档，点击try it out 可以模拟请求，类似postman功能。

自动API生成就这样子了。可以把路径给前端，让前端自己阅读了，省下我们编写API的时间。哈哈