swagger的创建(SpringBoot)

https://www.bilibili.com/video/av37961314/?p=6

跟着视频做的

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

作用:

      接口的文档在线自动生成;

      功能测试

1.创建springboot项目(Spring Initializr)-web(Spring Web Starter)

2.修改pom.xml文件,添加swagger依赖

<!--swagger-api 依赖开始-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.1</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.1</version>
        </dependency>

        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.6.6</version>
        </dependency>
<!--swagger-api 依赖结束-->

3.swagger配置

在com.zt.springboot下新建config包,在config下新建SwaggerConfig类和WebMvcConfig类

package com.zt.springboot.config;

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

/**
 * @author zt
 * @date 2019/6/20 10:17
 */
@Configuration//配置类注解
@EnableSwagger2//启动
@EnableWebMvc
//扫描Controller包
//@ComponentScan(basePackages = {"com.zt.springboot.controller"})
public class SwaggerConfig {

    @Bean
    public Docket buildDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//调用下面apiInfo()方法
                .select()
                //Controller所在路径
                .apis(RequestHandlerSelectors.basePackage("com.zt.springboot.controller"))
                .paths(PathSelectors.any())
                .build();

    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("测试项目 API")
                .description("API接口文档")
//                .termsOfServiceUrl("")
                .contact("zt")
                .version("0.0.1")
                .build();
    }
}

package com.zt.springboot.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

/**
 * @author zt
 * @date 2019/6/20 10:36
 */
@Configuration
class WebMvcConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

4.在com.zt.springboot下新建controller包,在controller下新建UserController类(创建User类,属性有id,name,age)

package com.zt.springboot.controller;

import com.zt.springboot.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.mapstruct.ValueMapping;
import org.springframework.web.bind.annotation.*;

import java.nio.file.Path;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

/**
 * @author zt
 * @date 2019/6/20 10:41
 */

@RestController
@Api(value = "用户controller",description = "用户模块接口信息",tags = "用户管理-用户列表")
public class UserController {
    //模拟数据库
    public static List<User> users = new ArrayList<>();
    static {
        users.add(new User(1001,"张三",23));
        users.add(new User(1002,"lisi",24));
    }

    @ApiOperation(value = "获取用户列表(请求标题)",notes = "获取所有用户的列表(展开note)",tags = {"@zt"})
    //获取用户列表方法
//    @RequestMapping("/users")//所有
    @GetMapping("/users")
//    @PostMapping("/users")
    public Object Users(){
        Map<String,Object> map = new HashMap<>();
        map.put("users",users);
        return map;
    }

    //tags = {"@zt"}  tags可以重新分组（视情况而用）
    @ApiOperation(value = "查询单个用户",notes = "根据ID查询某个用户的信息",tags = {"@zt"})
    @ApiImplicitParam(value = "用户的ID",paramType = "path")
    @GetMapping("/users/{id}")
    public User getUserById(@PathVariable("id") int id){
        return users.get(id);
    }

    @ApiOperation(value = "添加用户",notes = "添加用户详情",tags = {"@zt"})
    @ApiImplicitParam(value = "用户对象",paramType = "query")//有值??
    @PostMapping("/users")
    public Object addUser(User user){
        return  users.add(user);
    }

    @ApiOperation(value = "删除用户",notes = "根据ID查询删除用户的信息",tags = {"@zt"})
    @ApiImplicitParam(value = "用户的ID",paramType = "path")
    @DeleteMapping("users/delete/{id}")
    public Object deleteUser(@PathVariable("id") int id){
        return users.remove(id);
    }
}

5.记得在***Application中添加

@EnableWebMvc

6.运行页面

Swagger的常用注解说明

https://www.cnblogs.com/yueguanguanyun/p/9041690.html

https://blog.csdn.net/it_erge/article/details/91492997

@ApiImplicitParam注解的dataType、paramType两个属性的区别？

@ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "int",paramType = "body")
dataType="int" 代表请求参数类型为int类型，当然也可以是Map、User、String等；

paramType="body" 代表参数应该放在请求的什么地方：

    header-->放在请求头。请求参数的获取：@RequestHeader(代码中接收注解)
    query-->用于get请求的参数拼接。请求参数的获取：@RequestParam(代码中接收注解)
    path（用于restful接口）-->请求参数的获取：@PathVariable(代码中接收注解)
    body-->放在请求体。请求参数的获取：@RequestBody(代码中接收注解)
    form（不常用）

 

一些swagger的使用说明

https://www.cnblogs.com/softidea/p/6251249.html

https://blog.csdn.net/ajklaclk/article/details/80736042