Swagger2

背景介绍

在团队开发中,一个好的 API 文档不但可以减少大量的沟通成本,还可以帮助一位新人快速上手业务。传统的做法是由开发人员创建一份 RESTful API 文档来记录所有的接口细节,并在程序员之间代代相传。这种做法存在以下几个问题:

1)API 接口众多,细节复杂,需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等,想要高质量的完成这份文档需要耗费大量的精力;

2)难以维护。随着需求的变更和项目的优化、推进,接口的细节在不断地演变,接口描述文档也需要同步修订,可是文档和代码处于两个不同的媒介,除非有严格的管理机制,否则很容易出现文档、接口不一致的情况;

Swagger2 的出现就是为了从根本上解决上述问题。它作为一个规范和完整的框架,可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务:

  • 接口文档在线自动生成,文档随接口变动实时更新,节省维护成本;
  • 支持在线接口测试,不依赖第三方工具;

什么是Swagger2

Swagger2 是一个规范和完整的框架,用于生成、描述、调用和可视化Restful风格的web服务,现在我们使用spring boot 整合它。作用:

  • 接口的文档在线自动生成;
  • 功能测试;

常用注解

注解 描述
@Api 将类标记为 Swagger 资源。
@ApiImplicitParam 表示 API 操作中的单个参数。
@ApiImplicitParams 允许多个 ApiImplicitParam 对象列表的包装器。
@ApiModel 提供有关 Swagger 模型的其他信息。
@ApiModelProperty 添加和操作模型属性的数据。
@ApiOperation 描述针对特定路径的操作或通常是 HTTP 方法。
@ApiParam 为操作参数添加额外的元数据。
@ApiResponse 描述操作的可能响应。
@ApiResponses 允许多个 ApiResponse 对象列表的包装器。
@Authorization 声明要在资源或操作上使用的授权方案。
@AuthorizationScope 描述 OAuth2 授权范围。

SpringBoot整合Swagger2

导入依赖


    io.springfox
    springfox-swagger2
    2.9.2
    
        
            swagger-models
            io.swagger
        
    



    com.github.xiaoymin
    swagger-bootstrap-ui
    1.8.5




    io.swagger
    swagger-models
    1.5.22

创建Swagger配置类

@Configuration
//开启Swagger2
@EnableSwagger2
//配置生产环境下不可用  dev(开发)、test(测试)、prod(生产)
@Profile({"dev","test"})
public class Swagger2Configuration extends WebMvcConfigurationSupport {
    //api接口包扫描路径
    public static final String
            SWAGGER_SCAN_BASE_PACKAGE = "com.lky.swagger2pro.controller";
    //指定当前Swagger API文档版本
    public static final String VERSION = "1.0.0";

    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 接口文档的基本信息
                .apiInfo(apiInfo())
                .select()
                // 方法需要有ApiOperation注解才能生存接口文档
                //.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 路径使用any风格
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息(这些基本信息会展现在文档页面中)
     * 访问地址:http://项目实际地址/doc.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot中使用Swagger2构建RestFul APIs")
                .description("测试系统")
                //.termsOfServiceUrl("http://www.**.com")
                .version(VERSION)
                .build();
    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}
  1. 完成以上配置之后,通过mybatis-generator生成model和mapper;
  2. 创建IBookService及BookServiceImpl实现类;
  3. 创建BookController

综合案例

localhost:8080/doc.html

Swagger2_第1张图片

@Api

@Api注解用在类上,说明该类的作用。可以标记一个Controller类做为swagger文档资源。

属性 说明
value url的路径值
tags 如果设置这个值、value的值会被覆盖
produces 返回的格式类型例如:“application/json, application/xml”
consumes 接收请求参数的类型例如:“application/json, application/xml”
protocols Possible values: http, https, ws, wss.
authorizations 高级特性认证时配置

案例演示

@RestController
@Api(value = "书本管理",tags = {"书本管理"}) //tags可以代替value属性
@RequestMapping("/book")
public class BookController {
    ...
}

@ApiOperation

@ApiOperation注解用在方法上,说明方法的作用,每一个url资源的定义。

属性 说明
value url的路径值
tags 如果设置这个值、value的值会被覆盖
produces 返回的格式类型例如:“application/json, application/xml”
consumes 接收请求参数的类型例如:“application/json, application/xml”
hidden 是否在文档中显示
notes 注释说明
response 返回的对象
responseContainer 这些对象是有效的 “List”, “Set” or “Map”.,其他无效
responseReference 指定对响应类型的引用。指定的引用可以是本地的,也可以是远程的*将按原样使用,并覆盖任何指定的response()类
responseHeaders 响应旁边提供的可能标题列表
httpMethod “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
code http的状态码 默认 200

案例演示

@ApiOperation(value = "查询所有书本信息", notes = "查询返回所有书本信息集合",
            produces = "application/json")
@GetMapping(value="/queryAll")
public JsonResponseBody> queryAll(){
    try {
        return bookService.queryAll();
    } catch (Exception e) {
        e.printStackTrace();
        return new JsonResponseBody<>(500,e.getMessage());
    }
}

@ApiImplicitParam

@ApilmplicitParam 注解用来描述一个参数,可以配置参数的中文含义,也可以给参数设置默认值,这样在接口测试的时候可以避免手动输入;

属性 说明
paramType 参数放在哪个地方
name 参数名称
value 参数代表的含义
dataType 参数类型
dataTypeClass 参数类型
required 是否必要
defaultValue 参数的默认值

paramType

类型 作用
path 以地址的形式提交数据,用于restful接口。请求参数采用@PathVariable获取
query 直接跟参数完成自动映射赋值。请求参数可采用@RequestParam获取
body 以流的形式提交,仅支持POST。请求参数采用@RequestBody获取
header 参数在request headers里边提交。请求参数采用@RequestHeader获取
form 以form表单的形式提交,仅支持POST。

案例演示

@ApiOperation(value="查询单个书本信息",notes = "查询单个书本信息")
@ApiImplicitParam(value="书本ID",name="bookid",required = true,dataType = "String",defaultValue = "8f46b5018a6811e9a9c528d24413c293" )
@GetMapping("/querySingleBook")
public Book querySingleBook(String bookid){
    JsonResponseBody json = bookService.selectByPrimaryKey(bookid);
    return json.getData();
}

@ApiImplicitParams

@ApilmplicitParams 如果有多个参数,则需要使用多个 @ApilmplicitParam 注解来描述, 多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中;

案例演示

@ApiOperation(value = "新增书本信息", notes = "新增书本信息"
            ,produces = "application/json",consumes = "application/json")
@ApiImplicitParams({
            @ApiImplicitParam(name="bookname",value="书本名称",required = true,dataType = "String"),
            @ApiImplicitParam(name="price",value="书本价格",required = true,dataType = "Double"),
            @ApiImplicitParam(name="booktype",value="书本类型",required = true,dataType = "String")
})
@PostMapping("/addBook")
public JsonResponseBody addBook(@RequestParam String bookname,
                                   @RequestParam Double price,
                                   @RequestParam String booktype){
    return bookService.insert(Book.builder()
        .bookid(UUID.randomUUID().toString().replace("-",""))
        .bookname(bookname)
        .booktype(booktype)
        .price(price)
        .build());
}

@ApiModel和@ApiModelProperty

@ApiModel注解描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用 @ApiImplicitParam注解进行描述的时候;

@ApiModelProperty注解描述一个model的属性。

属性 说明
value 字段说明
name 参数名称
dataType 参数类型
hidden 在文档中隐藏
required 是否必要
example 举例说明
notes 注释说明

案例演示

Controller

@ApiOperation(value="修改书本信息",notes = "修改书本信息")
@PostMapping("/editBook")
public JsonResponseBody editBook(@RequestBody Book book){
    return bookService.updateByPrimaryKey(book);
}

注意:在这里可以不使用@ApiImplicitParam标注Swagger中的参数信息,因为在这里的输入参数是实体对象,而在实体对象中已经使用@ApiModel和@ApiModelProperty注解进行了标识。

Book实体类

@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value="书本对象")
public class Book implements Serializable {

    /**
     * 书本编号
     */
    @ApiModelProperty(value="书本编号")
    private String bookid;

    /**
     * 书本名称
     */
    @ApiModelProperty(value="书本名称")
    private String bookname;

    /**
     * 书本价格
     */
    @ApiModelProperty(value="书本价格")
    private Double price;

    /**
     * 书本类型
     */
    @ApiModelProperty(value="书本类型")
    private String booktype;

    private static final long serialVersionUID = 1L;
}

@ApiParam

作用在方法的参数上,用来描述接口的参数信息(一个参设置一个)

@ApiParam必须与@RequestParam@PathVariable@RequestHeader一起使用。

属性 说明
name 参数名称
value 参数简单描述
defaultValue 描述参数默认值
required 是否为必传参数, false:非必传; true:必传
allowMultiple 指定参数是否可以通过多次出现来接收多个值
hidden 隐藏参数列表中的参数
example 非请求体(body)类型的单个参数示例
examples @Example(value = @ExampleProperty(mediaType = “”, value = “”)) 参数示例,仅适用于请求体类型的请求

案例演示

@ApiOperation(value="新增书本信息1",notes="新增书本信息1")
@PostMapping("/addBooks")
public JsonResponseBody addBooks(
            @ApiParam(name="bookName",value="bookName",required = true) @RequestParam("bookName") String bookName,
            @ApiParam(name="price",value="price",required = true) @RequestParam("price") float price,
            @ApiParam(name="bookType",value="bookType",required = true) @RequestParam("bookType") String bookType){
      System.out.println("bookName="+bookName+",price="+price+",bookType="+bookType);
    return new JsonResponseBody<>();
}

生产环境下屏蔽Swagger2

为了保证接口文档的安全,禁用了生产环境的加载,具体说明请看:

参考地址:https://www.jianshu.com/p/fa3230ffb27c

一般生产环境是不能放开swagger的,这样接口暴露在外网很不安全!!!

一般生产环境是不能放开swagger的,这样接口暴露在外网很不安全!!!

一般生产环境是不能放开swagger的,这样接口暴露在外网很不安全!!!

修改Swagger2配置类

添加@Profile注解,指明在何种环境下可以使用Swagger2,一般情况下只有在开发(dev)和测试(test)环境下才可以使用Swagger2;而在生产(dev)环境下不能使用Swagger2。

@Configuration
//开启Swagger2
@EnableSwagger2
//配置生产环境下不可用  dev(开发)、test(测试)、prod(生产)
@Profile({"dev","test"})
public class Swagger2Configuration extends WebMvcConfigurationSupport {
    
    ...

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html")
.addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

修改application.yml

修改application.yml文件,配置项目系统的运行环境(dev/test/prod)

spring:
  #配置swagger2生产和测试环境不可用
  profiles:
    active: prod

使用maven package打包测试

Swagger2_第2张图片

运行测试

打开CMD,跳转到target目录,输入命令:java -jar .\xxx.jar --spring.profiles.active=prod。可以直接打开jar包修改application.yml配置文件中spring.profiles.active属性切换运行环境,具体请参考以下配置:

开发环境:dev;
生产环境:prod;
测试环境:test;

Swagger2_第3张图片

你可能感兴趣的:(Java,spring,boot,java,spring)