> 文档中心 > [Swagger]-Swagger学习

[Swagger]-Swagger学习


Swagger学习

参考视频链接
官方文档链接

SpringBoot集成Swagger

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.创建Swagger配置类

@EnableSwagger2  //开启Swagger2@Configuration   //标志该类是项目的配置类public class Swagger2Config {}

3.访问项目的swagger-ui.html就是ui界面
swaggerui示例图
可以看到ui界面大体可以分为四部分:选择框,api信息,控制层请求接口信息以及项目的model实体类信息

配置swagger

swagger的配置需要一个Docket类的bean。而Docket类的构造函数只有一个:

public Docket(DocumentationType documentationType) {    this.apiInfo = ApiInfo.DEFAULT;    ......    this.documentationType = documentationType;}

DocumentationType类中有三个static final修饰的DocumentationType变量:

public class DocumentationType extends SimplePluginMetadata {    public static final DocumentationType SWAGGER_12 = new DocumentationType("swagger", "1.2");    public static final DocumentationType SWAGGER_2 = new DocumentationType("swagger", "2.0");    public static final DocumentationType SPRING_WEB = new DocumentationType("spring-web", "1.0");    ...}

所以Docket的构造函数只需传入DocumentationType.SWAGGER_2即可。这样构造出Docket后其中的属性都是默认的,可使用其中的方法对属性进行配置
apiInfo方法可以配置api信息;enable方法可以指定是否开启Swagger;groupName方法可以指定该docket的接口api的组名;tags方法可以配置某些标签,可以在描述控制器的名称或描述信息等时使用(后续的@Api注解);forCodeGeneration方法可以设置泛型在编码时的格式,具体在文档中的描述是这样的:
forCodeGeneration方法官网描述

配置api信息

Docket中的apiInfo方法可以配置api的信息。该方法需要传入一个ApiInfo类对象,该类中包括以下信息:

private final String version;    //项目版本号private final String title;      //项目标题private final String description;//项目等的描述private final String termsOfServiceUrl; //服务条款urlprivate final String license;    //证书private final String licenseUrl; //证书url  private final Contact contact;   //联系人  private final List<VendorExtension> vendorExtensions; //其它扩展信息

ApiInfo类中只提供了全参构造器以及各属性的get方法没有set方法,所以可以使用全参构造器构造ApiInfo类对象。除此之外可以使用ApiInfoBuilder类来构造ApiInfo,借助ApiInfoBuilder可以通过单个方法设置ApiInfo的各项属性,比直接调用ApiInfo类的全参构造器就更灵活且简洁,设置完属性调用build方法就可以返回一个ApiInfo对象,该方法实际上也是在调用ApliInfo的全参构造方法

配置标签

通过Docket中的tags方法可以设置标签,该方法接收一个Tags对象,一般使用Tag(String name, String description)构造方法构造,指定tag的名称以及该tag要描述的信息。被构造出来的标签不管有没有被使用到类或方法上都会在ui界面上显示出来
使用时只需在控制器类上加@Api注解,然后将其中的tags属性指定为某个Tags的name属性即可将这个类与这个标签绑定在一起
当然请求方法也可以跟某个tags绑定在一起,但是这样的话会造成方法跟类之间没有层级关系而是平行关系,可读性降低了

配置接口信息

接口扫描

通过Docket的select方法会得到该Docket的ApiSelectorBuilder类对象,该对象就是用于配置api接口信息的
通过apis方法指定扫描接口的方式,该方法接受一个泛型为RequestHandler接口类型的Predicate接口参数,RequestHandlerSelectors类中对此有具体的实现:basePackage方法可以指定扫描某个包下的请求接口;any扫描全部接口;none都不扫描;withClassAnnotation扫描有指定注解的类中的接口;withMethodAnnotation扫描有指定注解的方法上的接口
通过paths可以指定扫描哪些请求路径,类似于apis方法,该方法调用PathSelectors类中的方法作为参数:any指定扫描所有请求路径;none不扫描任何路径;ant方法接收一个字符串路径模式(如"/**"),指定扫描符合该指定模式的路径;regex方法接收一个正则表达式,指定扫描符合正则表达式的路径
接口的扫描指定好后,调用build方法即可得到原先的Docket
@ApiIgnore用于类或方法或参数上,表示被注解的项要被忽略

添加接口描述信息

@Api用在类上,添加整个类中的所有接口的描述信息(使用tags属性)
@ApiOperation用在方法上,添加方法(请求接口)的描述信息
@ApiParam用在方法参数(请求参数)前面,添加参数的描述信息以及参数是否必须等

配置api分组

一个项目中可以设定多个Docket,每个Docket配置自己的组名,接口api信息等其它性质,不同Docket的接口就是不同组的,在ui界面的选择框可以选择不同组别进行展示

配置实体类信息

只要控制层请求接口的返回值存在实体类,它就会被扫描到swagger中
实体类上加注解@ApiModel可以添加实体类的描述信息
实体类中的成员变量上加注解@ApiModelProperty可以添加字段的描述信息(如果成员变量是public修饰直接这样就可以,如果是private修饰就需要加上get和set方法才能生效)

代码示例

swagger配置类

@Configuration@EnableSwagger2public class SwaggerConfig {    @Bean    public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2)  .apiInfo(apiInfo())  .groupName("这里是GroupName")  .forCodeGeneration(true)  .tags(new Tag("这是标签的名字","这是标签对应要描述的信息"))  .tags(new Tag("这个标签创建了但是没有使用","还是会显示出来"))  .select()  .apis(RequestHandlerSelectors.basePackage("com.xxx.www.testcontroller"))  //.paths(PathSelectors.ant("/test/*"))  .build();    }    @Bean    public Docket docket2(){ return new Docket(DocumentationType.SWAGGER_2)  .groupName("这里是第二个GroupName");    }    public ApiInfo apiInfo(){ return new ApiInfoBuilder()  .title("这里是title")  .version("这里是version")  .description("这里是description")  .build();    }}

控制器

@Api(value = "这是类",tags = {"这是标签的名字"})@RestController@RequestMapping("/test")public class TestController {    @ApiOperation(value = "这是接口描述")    @GetMapping("/testUser")    public List<String> test(List<String> result) { return new ArrayList<String>();    }}

ui界面
ui界面示例

总结

正式发布时应关闭swagger,出于安全考虑,避免暴露接口,同时节约运行所需资源
swagger在代码层面需要做配置,注解等,具有一定的代码植入性