Swagger保姆级教学

Swagger 简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

快速上手

1.新建一个springboot项目

2.导入maven依赖(swagger2和swagger UI)

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger2</artifactId>

    <version>2.9.2</version>

</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger-ui</artifactId>

    <version>2.9.2</version>

</dependency>

3.启动项目，访问http://localhost:端口/swagger-ui.html

4.新建一个SwaggerConfig.java

package com.littlepage.config;

import java.util.ArrayList;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

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;

@Configuration

@EnableSwagger2

public class SwaggerConfig {

	/**

	 * 配置swagger bean实例

	 * @return

	 */

	@Bean

	public Docket docket() {

		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());

	}

	/**

	 * 配置swagger信息

	 * @return

	 */

	private ApiInfo apiInfo() {

		return new ApiInfo("steve yu's API document",

				"for quick start swagger", "1.0",

				"https://www.cnblogs.com/littlepage/",

				new Contact("steve yu", "https://www.cnblogs.com/littlepage/", "littlepageprogram@outlook.com"),

				"Apache 2.0","http://www.apache.org/licenses/LICENSE-2.0",new ArrayList<>());

	}

}

启动页面

5.配置扫描接口(修改Bean)

@Bean

public Docket docket() {

	return new Docket(DocumentationType.SWAGGER_2).

			apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.littlepage.controller")).build();

}

6.在环境中进行配置（工程扫描接口开关）

@Bean

public Docket docket(Environment environment){

	Profiles profiles=Profiles.of("dev","test");//假设有dev和test环境变量

	boolean flag=environment.acceptsProfiles(profiles);

	return new Docket(DocuemtatuionType.SWAGGER_2).enable(flag);//如果环境配置了，则生效，否则不生效

}

7.API文档的分组。

new Docket().group(String s)

//这个String s可以规定分组

8.单API样例(参考https://www.jianshu.com/p/349e130e40d5）

#####Controller代码

@Override

    @ApiOperation(value = "post请求调用示例", notes = "invokePost说明", httpMethod = "POST")

    public FFResponseModel<DemoOutputDto> invokePost(@ApiParam(name="传入对象",value="传入json格式",required=true) @RequestBody @Valid DemoDto input) {

        log.info("/testPost is called. input=" + input.toString());

        return new FFResponseModel(Errcode.SUCCESS_CODE, Errcode.SUCCESS_MSG);

    }

#####接口请求入参对象

@Data

@ApiModel(value="演示类",description="请求参数类" )

public class DemoDto implements Serializable {

    private static final long serialVersionUID = 1L;

    @NotNull

    @ApiModelProperty(value = "defaultStr",example="mockStrValue")

    private String strDemo;

    @NotNull

    @ApiModelProperty(example="1234343523",required = true)

    private Long longNum;

    @NotNull

    @ApiModelProperty(example="111111.111")

    private Double doubleNum;

    @NotNull

    @ApiModelProperty(example="2018-12-04T13:46:56.711Z")

    private Date date;

}

#####接口请求出参公共类

@ApiModel(value="基础返回类",description="基础返回类")

public class FFResponseModel<T> implements Serializable {

    private static final long serialVersionUID = -2215304260629038881L;

    // 状态码

    @ApiModelProperty(example="成功")

    private String code;

    // 业务提示语

    @ApiModelProperty(example="000000")

    private String msg;

    // 数据对象

    private T data;

...

}

#####接口请求出参实际数据对象

@Data

public class DemoOutputDto {

    private String res;

    @NotNull

    @ApiModelProperty(value = "defaultOutputStr",example="mockOutputStrValue")

    private String outputStrDemo;

    @NotNull

    @ApiModelProperty(example="6666666",required = true)

    private Long outputLongNum;

    @NotNull

    @ApiModelProperty(example="88888.888")

    private Double outputDoubleNum;

    @NotNull

    @ApiModelProperty(example="2018-12-12T11:11:11.111Z")

    private Date outputDate;

}

Swagger保姆级教学的相关教程结束。