springboot 中使用 swagger2 做接口文档说明

一、swagger 与 swagger2 的区别

1、Swagger 是一种规范。
2、springfox-swagger 是基于 Spring 生态系统的该规范的实现。
4、springfox-swagger-ui 是对 swagger-ui 的封装，使得其可以使用 Spring 的服务

二、springboot 中使用 springfox-swagger-ui

1、pom 文件中导入依赖

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<dependency><!--添加Swagger依赖 -->
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.7.0</version>
		</dependency>
		<dependency><!--添加Swagger-UI依赖 -->
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.7.0</version>
		</dependency>

2、配置 swagger bean
其中 com.wxw.dockerdemo1 是主包名

@Configuration //标记配置类
@EnableSwagger2 //开启在线接口文档
public class Swagger2Config {
    /**
     * 添加摘要信息(Docket)
     */
    @Bean
    public Docket controllerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("标题：wxw的_接口文档")
                        .description("描述：测试swagger...")
                        .contact(new Contact("wxw", null, null))
                        .version("版本号:1.0")
                        .build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wxw.dockerdemo1"))
                .paths(PathSelectors.any())
                .build();
    }
}

3、swagger2 注解
swagger通过注解生成接口文档，包括接口名、请求方法、参数、返回信息的等内容。

@Api：修饰整个类，描述Controller的作用
使用在Controller层Api类上，主要属性有tags(标签)、hidden(是否隐藏)、value、authorizations等

@ApiOperation：描述一个类的一个方法，或者说一个接口
value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”

@ApiParam：单个参数描述
required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dateType="变量类型”,paramType="请求方式“

@ApiModel：用对象实体来作为入参
用在实体类上，主要属性有description(描述)、parent(父类)、subTypes、value、discriminator等

@ApiProperty：用对象接实体收参数时，描述对象的一个字段
用在实体类属性上，主要属性有access、accessMode、allowableValues、allowEmptyValue(是否允许为空)、dataType(数据类型)、example(示例)、hidden(是否隐藏)、name(名称)、notes、required(是否必需)、value(说明)等

@ApiImplicitParam：一个请求参数
@ApiImplicitParams： 多个请求参数

使用在Api类的接口方法上，对接口参数进行说明，@ApiImplicitParams只有一个属性value，@ApiImplicitParam主要属性有name(参数名称)、value(参数说明)、required(是否必需)、dataType(数据类型)、paramType(参数类型)、dataTypeClass、defaultValue、readOnly等

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

4、使用 swagger 注解

我这边主要编写两个测试类，可以对应参考一下

@Api(value = "hello docker",tags = "测试dockers")
@RestController
public class DockerTest {

    @RequestMapping(value = "/helloDcker")
    @ApiOperation(value = "sayHelloDocker")
    public String hello(){
        return "Hello，docker，I'm,WXW";
    }
}

@Api(value = "hello swagger",tags = "测试swagger")
@RestController
public class SwaggerTest {

    @RequestMapping(value = "/helloSwagger" )
    @ApiOperation(value = "sayhelloSwagger",httpMethod = "GET")
    public String hello(){
        return "Hello，swagger，I'm,WXW";
    }
}

写好之后启动，访问 swagger

http://localhost:8888/swagger-ui.html#/

可以看到 DockerTest 这个 controller 里面的方法，会显示7个方法，不同的请求类型，因为 DockerTest 中 hello 方法没有指定方法请求类型，所以它不知道你的方法是什么请求类型，会给你显示7种所有的类型。

而 SwaggerTest 这个controller 里面的方法只会显示一个，因为 SwaggerTest 中 hello 方法有指定方法请求类型，httpMethod = “GET”。

swagger2 默认的界面会是英文版，我这里是经过汉化的版本，汉化教程在下面。

三、swagger2 汉化

1、先附上汉化成功后的文件目录截图

2、第一步，resources 目录下

先创建 META-INF/resources 目录
然后从项目的 maven jar 包中 复制这个文件进去

3、第二步，resources/META-INF/resources 中再创建

webjars/springfox-swagger-ui/lang

从项目的 maven jar 包中 复制这个文件放入 刚刚创建的 lang（也就是汉化的js）

4、第三步，编辑 resources 目录下 META-INF/resources 中的 swagger-ui.html 文件，加入下面两行

 <!--国际化操作：选择中文版 -->
    <script src='webjars/springfox-swagger-ui/lang/translator.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lang/zh-cn.js' type='text/javascript'></script>

最后重新加载一下项目，刷新一下页面， 就可以看到汉化之后的 swagger 页面了

swagger2 还有一些测试等其他的功能，就需要大家自己去使用了，这里只是简单写一下自己的一些理解。