Swagger2使用

一、引入pom依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!--如果觉得ui不好看可以换个漂亮的-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

二、编写配置类

package com.hi.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author hi
 * @program: nxt-cloud
 * @description:
 * @date 2021-07-13 11:38:56
 *
 * swagger2     默认访问地址  http://localhost:8080/swagger-ui.html
 * bootstrap-ui 默认访问地址  http://localhost:8080/doc.html
 * swagger-ui-layer 访问地址  http://localhost:8080/docs.html
 * swagger-mg-ui   http://localhost:8080/document.html
 * knife4j-spring-ui  http://localhost:8080/doc.html
 *
 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hi.controller"))
                .paths(PathSelectors.any())
                .build();
//                .globalOperationParameters(pars).groupName("nooyoo-auth"); // 分组
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * #配置swagger
     * #标题
     * title
     * #描述
     * description
     * #版本
     * version
     * #许可证
     * license
     * #许可证路径
     * licenseUrl
     * #服务条款URL
     * termsOfServiceUrl
     * #维护人名称
     * contact
     * #维护人url
     * contact.url
     * #维护人邮箱
     * contact.email
     * #swagger扫描的基础包，默认：全扫描
     * swagger.base-package=com.example.demo2
     * #需要处理的基础URL规则，默认：/**
     * swagger.base-path=/**
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("nxt")
                .description("测试")
                .termsOfServiceUrl("http://localhost:9999/doc.html")
                .contact(new Contact("hhy","",""))
                .version("1.0")
                .build();
    }
}

三、注解及说明

1、@Api 用在controller上

注解	说明
@Api	对请求类的说明

@Api 属性

属性名称	说明
tags	说明该类的作用，如果设置这个值、value的值会被覆盖
value	url的路径值，该参数没什么意义，所以不需要配置
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, “application/json, application/xml”
consumes	For example, “application/json, application/xml”
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏

2、用在方法上

注解	说明
@ApiOperation	用在请求的方法上，说明方法的作用，使用方式
@ApiImplicitParams	用在方法上包含一组参数说明，里面包含@ApiImplicitParam注解
@ApiImplicitParam	方法的参数的说明；@ApiImplicitParams 用于指定单个参数的说明
@ApiResponses	方法返回对象的说明
@ApiResponse	用在 @ApiResponses里边
@ApiIgnore	当作用在方法上时，方法将被忽略；作用在类上时，整个类都会被忽略；作用在参数上时，单个具体的参数会被忽略。（不会在接口文档显示）
@ApiParam	作用于方法的入参

1、@ApiOperation与Controller中的方法并列使用。

2、@ApiImplicitParams属性

属性名称	说明
name	参数名
value	参数的说明、描述
required	参数是否必须必填
dataType	参数类型，默认String，其它值dataType=“Integer”
defaultValue	参数的默认值
paramType	参数放在哪个地方

3、@ApiParam属性

属性	功能说明
name	名称
value	简单描述
defaultValue	参数值默认值
allowableValues	可接收参数限制
required	是否为必传参数
access	参数过滤
allowMultiple	指定参数是否可以通过多次出现来接收多个值
hidden	隐藏参数列表中的参数
example	非请求体(body)类型的单个参数示例
examples	参数示例，仅适用于请求体类型的请求

4、@ApiResponse属性

属性名称	说明
code	状态码、数字，例如400
message	信息
response	抛出异常的类

3、@ApiModel：用于JavaBean上面，表示对JavaBean 的功能描述

@ApiModel属性

属性	功能说明
value	值
description	描述

@ApiModelProperty属性

属性	功能说明
value	字段说明
name	重写属性名字
dataType	重写属性类型
required	是否必须(默认false)
example	举例说明
hidden	隐藏