Swagger接口文档

Swagger使用的注解及其说明：

@Api：用在类上，说明该类的作用。

@ApiOperation：注解来给API增加方法说明。

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

    l   code：数字，例如400

    l   message：信息，例如"请求参数没填好"

    l   response：抛出异常的类   

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

    l   @ApiModelProperty：描述一个model的属性

 

注意：@ApiImplicitParam的参数说明：

paramType：指定参数放在哪个地方	header：请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path：（用于restful接口）-->请求参数的获取：@PathVariable body：（不常用） form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传	true | false
value：说明参数的意思
defaultValue：参数的默认值

使用实例

@GetMapping("/query")
@ApiOperation(value = "查询列表")
@ApiImplicitParams({
        @ApiImplicitParam(paramType = "query", name = "title", dataType = "String", value = "订单名称"),
        @ApiImplicitParam(paramType = "query", name = "industryId", dataType = "Long", value = "行业分类"),
        @ApiImplicitParam(paramType = "query", name = "type", dataType = "String", value = "查询类型[myself,offer]，不传查询正常数据"),
        @ApiImplicitParam(paramType = "query", name = "call", dataType = "String", value = "是否联系过[Y,N]", defaultValue = "N"),
        @ApiImplicitParam(paramType = "query", name = "companyId", dataType = "Long", value = "官网下的供应产品"),
})

 

@Api(description = "订单池", tags = "采购相关接口")

    @ApiModelProperty(value = "可通话次数")
    private Long calls;

    @ApiModelProperty(value = "用户电话[任何新增修改不需要传入]")
    private String phone;

    @ApiModelProperty(value = "用户公司[任何新增修改不需要传入]")
    private String companyName;

    @ApiModelProperty(value = "用户头像")
    private String iconUrl;

    @ApiModelProperty(value = "用户公司ID[任何新增修改不需要传入]")
    private Long companyId;

Swagger与SprIngBoot的整合

   1) 导包

<dependency>
        <groupId>com.spring4all</groupId>
        <artifactId>swagger-spring-boot-starter</artifactId>
        <version>1.7.0.RELEASE</version>
</dependency>

   2)配置类 

@Configuration
@EnableSwagger2
public class SwaggerUiConfig {

    @Bean
    public Docket createRestApi() {
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        tokenPar.name("token").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        pars.add(tokenPar.build());
        return new Docket(DocumentationType.SWAGGER_2)
                .globalOperationParameters(pars)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxxx"))
                .paths(applicationConfig.showApi ? PathSelectors.any() : PathSelectors.none())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXXXAPP前端接口文档")
                .description("移动终端对应后端RESTful APIs")
                .version("1.0")
                .build();
    }
}