swagger-ui生成API

1、添加pom所需依赖：

<properties>
   <swagger.version>2.6.1</swagger.version>
</properties>
<!-- swagger 版本一致做个属性-->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>${swagger.version}</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>${swagger.version}</version>
</dependency>

2、添加配置类：

package net.xdclass.xdvideo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket buildDocket(){
        ParameterBuilder debugParam = new ParameterBuilder();
        List<Parameter> params = new ArrayList<>();
        debugParam.name("debug").description("值为true时，测试用，绕过加密")
                .modelRef(new ModelRef("string")).parameterType("header")
                .required(false).build();//header中的ticket参数非必填，传空也可以
        params.add(debugParam.build());
        return new Docket(DocumentationType.SWAGGER_2)
                .globalOperationParameters(params)
                .apiInfo(buildApiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("net.xdclass.xdvideo.controller"))
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo buildApiInfo(){
        Contact contact = new Contact("water","","[email protected]");
        return new ApiInfoBuilder().title("购物商城-平台管理API文档")
                .description("平台管理服务API")
                .contact(contact)
                .version("1.0.0").build();
    }

}

3、启动服务，访问地址：http://localhost:8080/swagger-ui.html

如果Controller类中的请求方法上只写了@RequestMapping没有指定具体方法，则是如下图：

建议controller层方法上写明具体的请求方式，譬如POST、GET、POST、PUT。

4、Swagger常用到的注解有：

①@Api(value = "用户相关操作-测试你接口",tags = {"user-tag"})：用于类上。

②@ApiOperation(value = "查询用户数据",notes = "根据搜索条件查询满足条件的用户数据集合")：用于请求的方法上。

③@ApiModel("用户信息请求参数类")：用于实体类上。

④@ApiModelProperty(value = "id",required = true,example = "2")：用于实体类的属性或方法上。

⑤@ApiResponses和 @ApiResponse用于请求方法上，例如：

@ApiResponses({

        @ApiResponse(code = 400,message = "请求参数没填好，可能类型不对"),
        @ApiResponse(code = 404,message = "请求路径没有或者页面跳转路径不对"),
        @ApiResponse(code = 200,message = "操作成功，响应数据-data-为新增的用户id"),
})

用于请求方法上。

⑥@ApiImplicitParam和@ApiImplicitParams用于请求方法上，例如：

@ApiImplicitParam(name = "id",value = "用户id",required = true)
@ApiImplicitParams({@ApiImplicitParam(name = "name",value = "名字"),
        @ApiImplicitParam(name = "age",value = "年龄")})
@ApiOperation(value = "查询用户数据",notes = "根据搜索条件查询满足条件的用户数据集合")
public Result<User> findUser(@RequestParam(value = "id") String id,
                             @RequestParam(value = "name",required = false) String name);

猜你喜欢