JavaEE：Swagger使用

说明：

Swagger是API规范，规范RESTful开发过程

1.在工程/pom.xml中导入swagger依赖包：

<dependencies>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>
</dependencies>

2.定义API：

(1)注解说明：

@Api：用在Controller的接口类定义上，表明是一个API
@ApiOperation：用于描述某个具体的请求路径
@ApiParam：用于描述请求为单参数
@ApiImplicitParam：用于描述请求有一个参数
@ApiImplicitParams：用于描述请求有多个参数
@ApiModel：用于描述请求参数为对象类型
@ApiModelProperty：用于描述请求参数为对象参数的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：请求路径HTTP响应整体描述
@ApiIgnore：用于忽略这个API
@ApiError：用于返回错误的信息
header：说明请求参数在headers头字段里
paramType：说明参数类型
path：说明请求参数为GET方式
query：说明给对应参数自动赋值
body：说明请求参数为POST流的形式
form：说明请求参数为form表单形式
dataType：说明参数类型
name：说明参数名
value：说明参数值的作用
required：规定参数是否必填  true必填   false非必填
defaultValue：表明默认值

(2)使用@Api定义API接口类：

@Api(value = "用户信息接口", description = "用户相关信息的增删改插接口") //@Api用于标记为接口
public interface UserApi {
    @ApiOperation("getUserInfo") //接口路径
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userNo", value = "用户ID", required = false, paramType = "path", dataType = "String") //配置接口方法的参数
    })
    User getUserInfo(String userNo);
}

(3)使用@ApiModelProperty("名称")标记实体类的属性，用于对属性进行说明：

//实体类
public class User {
    @ApiModelProperty("姓名")
    private String name;
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
}

3.创建Controller实现自定义API接口，类前加上@RestController注解：

@RestController
@RequestMapping
public class UserController implements UserApi {//UserApi为自定义接口，加了@Api
    @RequestMapping("/getUserInfo/{userNo}")
    @RequestBody
    public User getUserInfo(@PathVariable String userNo) {
        User u = new User();
        u.setName("杨");
        return u;
    }
}

4.启动类上标记@EnableSwagger2注解：

@SpringBootApplication
@EnableSwagger2 //开启swagger
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class,args);
    }
}

5.其他配置：

(1)SwaggerConfig：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("admin")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yyh.swagger2.web"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger文档页标题")
                .description("swagger文档页描述")
                .termsOfServiceUrl("http://")
                .version("1.0")
                .build();
    }
}

(2)WMConfig：

@Configuration
public class WMConfig extends WebMvcConfigurationSupport {
    @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/");
    }
}