swagger1_入门

1. 简单入门例子

1.1 环境搭建

1.1.1 引入依赖

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.0.8.RELEASE</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>swagger</artifactId>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- junit -->
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <scope>test</scope>
        </dependency>

        <!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.5.0</version>
        </dependency>

        <!-- swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.5.0</version>
        </dependency>
        <dependency>
            <groupId>org.apache.activemq</groupId>
            <artifactId>activemq-all</artifactId>
            <version>5.11.2</version>
        </dependency>

    </dependencies>

1.1.2 编写yml配置文件

server:
  port: 9000

1.1.3 编写swagger 配置类

package com.wlqk.core.config;

import io.swagger.annotations.ApiOperation;
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;

/**
 * @configuration: 声明是一个配置类,容器启动的时候初始化
 * @EnableSeagger2:通过@EnableSwagger2注解来启用Swagger2。
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.wlqk.core.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring Boot 测试使用 Swagger2 构建RESTful API")
                //创建人
                .contact(new Contact("MarryFeng", "http://www.baidu.com", ""))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }

}

1.1.4 编写启动类

package com.wlqk.core;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;


@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class,args);
    }
}

1.1.5 编写controller

package com.wlqk.core.controller;

import com.wlqk.core.utils.Result;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/user")
@Api(description = "用户接口")
public class DemoController {

    private static final Logger logger = LoggerFactory.getLogger(DemoController.class);


    /*
     * value:方法说明
     * notes:实现方式
     * httpMethod:接口请求方法
     * response:返回值是什么字节码类型的
     * */
    @ApiOperation(value = "根据id查询学生信息",
            notes = "查询数据库中某个的学生信息",
            httpMethod = "POST",
            response = Result.class
    )
    /*
     * 用于包装多个参数请求
     * @ApiImplicatParam：约束一个参数请求*/
    @ApiImplicitParams(
            {
                    /*
                     * name:参数的名字
                     * value：参数描述
                     * paramType:参数以什么方式让后台接收
                     * required:true是必须的，false 不是必须的
                     * dataType:数据类型*/
                    @ApiImplicitParam(name = "id", value = "学生ID",
                            paramType = "path", required = true, dataType = "Integer"),
                    @ApiImplicitParam(name = "name", value = "学生姓名",
                            paramType = "path", required = true, dataType = "String")
            }
    )
    @RequestMapping(value = "/{id}/{name}", method = RequestMethod.POST)
    public Result addUser(@PathVariable Integer id, @PathVariable String name) {
        System.out.println(id + ":" + name);
        return new Result("OK", "操作成功");
    }

}

1.1.5 编写包装类

public class Result {

    private String code;

    private String msg;
    }

1.2 测试

2. 简单解析

3. 常用注解

@ApiImplicitParams、@ApiImplicitParam：方法参数的说明

• @ApiImplicitParams：用在请求的方法上，包含一组参数说明里面是一组ApilmplicitParam
• @ApiImplicitParam：对单个参数的说明

属性介绍

属性名称	备注
name	参数名
value	参数的汉字说明、解释
required	参数是否必须传
paramType	参数放在哪个地方
“”	header --> 请求参数的获取：@RequestHeader
“”	query --> 请求参数的获取：@RequestParam
“”	path（用于restful接口）–> 请求参数的获取：@PathVariable
“”	body（请求体）–> @RequestBody User user
“”	form（不常用）
dataType	参数类型，默认String，其它值dataType=“Integer”
defaultValue	参数的默认值

代码示范

@ApiOperation(value="用户登录",notes="手机号、密码都是必输项，年龄随边填，但必须是数字")
@ApiImplicitParams({
@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
@PostMapping("/login")
public JsonResult login(@RequestParam String mobile, @RequestParam String password,
@RequestParam Integer age){

    return JsonResult.ok(map);

@ApiOperation

• @ApiOperation：“用在请求的方法上，说明方法的作用”

属性介绍

属性名称	备注
value	“说明方法的作用”
notes	“方法的操作说明”
tags	对当前接口进行分组
response	设置返回类型

@Api属性配置

属性介绍

属性名称	备注
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径
position	如果配置多个Api 想改变显示的顺序位置
produces	如, “application/json, application/xml”
consumes	如, “application/json, application/xml”
protocols	协议类型，如: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true ，将在文档中隐藏

代码示范

   @Api(tags="APP登录授权")
@Controller
public class ApiLoginController {
}

@ApiResponses、@ApiResponse：方法返回值的说明

• @ApiResponses：方法返回对象的说明
• @ApiResponse：

属性名称	备注
code	数字，例如400
message	信息，例如"请求参数没填好"
response	抛出异常的类

代码示范

@ApiOperation("获取用户信息")
@ApiImplicitParams({
	@ApiImplicitParam(paramType = "query", name = "userId", dataType = "String", required = true, value = "用户Id")
}) 
@ApiResponses({
	@ApiResponse(code = 400, message = "请求参数没填好"),
	@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
}) 
@ResponseBody
@RequestMapping("/list")
public JsonResult list(@RequestParam String userId) {
	...
	return JsonResult.ok().put("page", pageUtil);
}

@ApiModel、@ApiModelProperty：用于响应类上，表示一个返回响应数据的信息

• @ApiModel：用于响应类上，表示一个返回响应数据的信息
  （这种一般用在post创建的时候，使用@RequestBody这样的场景，
  请求参数无法使用 @ApiImplicitParam 注解进行描述的时
• @ApiModelProperty：用在属性上，描述响应类的属性

@ApiModel(description= "返回响应数据")
public class RestMessage implements Serializable{

	@ApiModelProperty(value = "是否成功")
	private boolean success=true;
	@ApiModelProperty(value = "返回对象")
	private Object data;
	@ApiModelProperty(value = "错误编号")
	private Integer errCode;
	@ApiModelProperty(value = "错误信息")
	private String message;
		
	/* getter/setter */
}