Swagger学习笔记

什么是Swagger

Swagger使用于前后端分离开发的一款框架，能够动态的显示接口的信息并且对接口进行调试。优点为使用方便，配置简单，减少工作量等。访问路径（项目完整路径 + swagger-ui.html）注：Swagger推荐使用Restful接口开发规范
Swagger官网
DemoGithub

Swagger的配置

Swagger依赖

<!-- 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>

配置

package com.tqb.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.web.bind.annotation.RestController;
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;

import java.util.ArrayList;

/**
 * @ClassName SwaggerConfig
 * @Description: TODO
 * @Author 田清波
 * @Mail tqb820965236@163.com
 * @Date 2019/10/3 15:40
 * @Version v1.0
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     *
     * @param environment 验证当前项目处于的环境（如生产 开发 测试等）
     * @return
     */
    @Bean
    public Docket docket(Environment environment){

        /**
         * 可用swagger的环境
         */
        Profiles of = Profiles.of("dev", "test");
        boolean flag = environment.acceptsProfiles(of);

        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        docket.apiInfo(apiInfo())
                /**
                 * 设置swagger是否可用 主要用于不同环境
                 */
                .enable(flag)
                .select()
                /**
                 * 只扫描具有RestController注解的类
                 */
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                /**
                 * 过滤器
                 */
                // .paths()
                .build();
        return docket;
    }

    /**
     * 接口文档基本信息
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfo(
                "Swagger的测试接口在线文档",
                "接口文档描述",
                "V1.0",
                "urn:tos",
                contact(),
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }

    /**
     * 接口文档编写作者
     * @return
     */
    private Contact contact(){
        return new Contact("bobo", "https://blog.csdn.net/weixin_42061805", "tqb820965236@163.com");
    }

}

使用

注解

1. @Api：主要用于接口描述（Controller）
   
2. @ApiOperation ： 接口具体方法的描述
   
3. @ApiModel ： 实体类的描述
4. @ApiModelProperty ： 实体类中属性的描述
   
5. @ApiParam ： 具体方法中参数的描述

代码

1. 实体类

package com.tqb.swagger.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

/**
 * @ClassName Student
 * @Description: TODO
 * @Author 田清波
 * @Mail tqb820965236@163.com
 * @Date 2019/10/5 12:51
 * @Version v1.0
 */
@ApiModel("学生实体类")
public class Student {
    @ApiModelProperty(value = "姓名", required = true)
    private String name;
    @ApiModelProperty(value = "性别", required = true)
    private String sex;
    @ApiModelProperty(value = "地址", required = true)
    private String address;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getSex() {
        return sex;
    }

    public void setSex(String sex) {
        this.sex = sex;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }
}

2. Controller

package com.tqb.swagger.controller;

import com.tqb.swagger.pojo.Student;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

/**
 * @ClassName DemoController
 * @Description: TODO
 * @Author 田清波
 * @Mail tqb820965236@163.com
 * @Date 2019/10/3 14:47
 * @Version v1.0
 */
@RestController
@Api(tags = "Demo的Controller层", value = "/Demo")
public class DemoController {

    @GetMapping("hello")
    @ApiOperation(value = "hello接口", notes = "田青菠 2019-10-5", httpMethod = "GET")
    public String hello(){
        return "hello";
    }


    @PostMapping("student")
    @ApiOperation(value = "添加学生", notes = "田青菠 2019-10-5", httpMethod = "POST")
    public Student student(@RequestBody Student student){
        return student;
    }
}

其它

使用Restful开发中常用的注解

1. @RequestBody ： 请求参数中的实体类
2. @PathVariable(value = “id”,required = true) ： 请求路径中携带的参数
3. @GetMapping ： 请求方法

启动页面