swagger2的基本使用

一、配置

2.1 依赖

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

2.2 spring boot配置 

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.jwell.iot.api.controller"))//对指定包进行接口文档生成
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .version("1.0")
                .description("园区物联网平台相关接口")
                .contact("me")
                .title("园区物联网平台相关")
                .build();
    }
}

二、常用注解及其参数

1.1 标注类

• @Api：用在controller头上,描述class
  • value：
  • description：对class的描述
• @ApiModel：用于实体类

1.2 标注方法

• @ApiOpration
  • value：描述方法
• @ApiImplicitParams：包含多个@ApiImplicitParam
• @ApiImplicitParam
  • name: 参数名
  • value：参数的描述
  • required：是否必须
  • dataType：参数类型
  • example：默认值
• @ApiResponses：不常用
• @ApiResponse

1.3 标注实体类的属性

• @ApiModelProperty
  • name：给属性设置名称，swaggerUI中显示，不常用
  • value：描述属性
  • required：是否必须
  • dataType：描述属性数据类型
  • example：设置默认值
  • hidden：是否隐藏

三、访问

http://ip:port/swagger-ui.html