springboot+swagger

Swagger是一个开源软件框架，由大型工具生态系统支持，可帮助开发人员设计，构建，记录和使用RESTful Web服务。虽然大多数用户通过Swagger UI工具识别Swagger，但c工具集包括对自动文档，代码生成和测试用例生成的支持。

使用了c我们能做什么呢？

想问一下广大的后端开发者是否为了在接口开完完成的时候因为需要些接口文档而烦恼，当然网上很多接口文档书写工具，但是从现在开始，你们可以省去写接口文档的时间了，不需要再为写接口文档而烦恼，使用了swagger能省去开发者省去写接口文档的时间，而且swagger是基于restful的接口框架，开发者只需要贴注解，写注释就能够自动生成接口文档，听起来是不是很强大很方便，没错swagger就是这么强大

如何在项目中集成swagger？

那么重点来了，下面就以SpringBoot项目集成swagger举例

首先需要导入Maven依赖

io.springfox springfox-swagger2 2.7.0 io.springfox springfox-swagger-ui 2.7.0 接着新建一个swaggerconfig的配置类进行swagger独有的配置

package com.ndltd.pay.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
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.ApiKey;
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;

import static com.google.common.collect.Lists.newArrayList;

@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {

@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/");
    registry.addResourceHandler("/swagger/**").addResourceLocations("classpath:/static/swagger/");
}


@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .globalOperationParameters(paramters())
            .apiInfo(apiInfo())
            .select()
            //加了ApiOperation注解的类，才生成接口文档
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            //包下的类，才生成接口文档
            //.apis(RequestHandlerSelectors.basePackage("io.demo.controller"))
            .paths(PathSelectors.any())
            .build()
            .securitySchemes(security());
}
private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("这是标题")
            .description("swagger接口文档")
            .termsOfServiceUrl("这是URL")
            .version("1.0")
            .build();
}

}
可能到这里有有人问，这么快？没错，就是这么快，这么简单，我们的SpringBoot项目就集成了swagger了，接下来就是用了，下面就是各常用注解的使用。

@Api(description =“贴在类上，整个controller的注释”)

@ApiOperation(value =“贴在方法上，方法的注释”)

@ApiModelProperty(value =“贴在对象里的字段上”)

注：当你需要的参数是一个对象的时候，对象里的字段是不是无法进行注释，当你在字段上贴上此注解即可

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

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

@ApiResponses：用于表示一组响应

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

l code：数字，例如400

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

l response：抛出异常的类

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

补充说明：

paramType：指定参数放在哪个地方header：请求参数放置于Request Header，使用@RequestHeader获取

query：请求参数放置于请求地址，使用@RequestParam获取

path：（用于restful接口）–>请求参数的获取：@PathVariable

body：（不常用）

form（不常用）

name：参数名

dataType：参数类型

required：参数是否必须传 true /false

value：说明参数的意思

defaultValue：参数的默认值

总结的不好，请见谅！

发布于 2019-01-09