Swaggerr

Swaggerr

• 号称世界上最流行的Api框架；
• RestFul Api 文档在线自动生成工具=>Api文档与API定义同步更新
• 直接运行，可以在线测试API接口；
• 支持多种语言：（Java，Php…）

依赖：

官网：https://swagger.io/

在项目使用Swagger需要 springfox；

• swagger2
• ui

springboot集成 Swagger

依赖

<!-- swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

Swagger配置类

@Configuration
@EnableSwagger2
public class Swaggerconfiger {

}

访问：http://localhost:8080/swagger-ui.html

Swagger的配置

文档信息

@Configuration
@EnableSwagger2
public class Swaggerconfiger {
    //Swagger的实例就是Docket
    @Bean
    public Docket docket(){

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo());
    }
    //修改Docket的默认配置
    public ApiInfo getApiInfo(){

        Contact DEFAULT_CONTACT = new Contact("first-blod", "xxx", "xxxx");
        ApiInfo apiInfo = new ApiInfo("dayday 的文档",
                "swagger-demo Documentation",
                "1.0", "urn:tos",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
        return  apiInfo;
    }
}

扫描的包

//Swagger的实例就是Docket
@Bean
public Docket docket(){
    Docket docket = new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(getApiInfo())
            //修改要扫描的地方
            .select().apis(RequestHandlerSelectors.basePackage("com.example.controller"))
            .build();
    return docket;
}

分组

Swagger注释

参考

Api

@Api 用在类上，说明该类的作用。可以标记一个 Controller 类作为 Swagger 文档资源，使用方式代码如下所示。

@Api(tags={"用户接口"})
@RestController
public class UserController {

}

ApiModel

@ApiModel 用在类上，表示对类进行说明，用于实体类中的参数接收说明。使用方式代码如下所示。

@ApiModel(value = "名称",description = "用户")

ApiModelProperty

@ApiModelProperty() 用于字段，表示对 model 属性的说明。使用方式代码如下所示。

@ApiModelProperty(value = "用户名")

ApiParam

@ApiParam 用于 Controller 中方法的参数说明。

ApiOperation

@ApiOperation 用在 Controller 里的方法上，说明方法的作用，每一个接口的定义。使用方式代码如下所示。

• value：接口名称
• notes：详细说明

ApiResponse 和 ApiResponses

@ApiResponse 用于方法上，说明接口响应的一些信息；@ApiResponses 组装了多个 @ApiResponse。使用方式代码如下所示。

@ApiResponses({ @ApiResponse(code = 200, message = "OK", response = UserDto.**class**) })

ApiImplicitParam 和 ApiImplicitParams

用于方法上，为单独的请求参数进行说明。使用方式代码如下所示。

@ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "用户ID", dataType = "string", paramType = "query", required = **true**, defaultValue = "1") })

• name：参数名，对应方法中单独的参数名称。
• value：参数中文说明。
• required：是否必填。
• paramType：参数类型，取值为 path、query、body、header、form。
• dataType：参数数据类型。
• defaultValue：默认值。