springboot2.0 快速学习集成swagger

作为一个后端开放者，当你开发完API接口后为写文档而烦恼吗？当app开发人员或前端开发人员看不懂的你写的接口文档，你还得去给他们讲一遍怎么使用而烦恼吗？使用我介绍的swagger 这些烦恼统统的消失。swagger 一个集预览和测试于一身的在线可视化 RESTful 风格的 Web 服务框架。

好拉我们不扯蛋直接切入正题体，在SpringBoot 中使用swagger 第一个步先引入swagger的依赖到pom 文件中。

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.7.0</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.7.0</version>
</dependency>

编写API 服务：一个用户的增删改查。

package cn.lijunkui.springbootlearn.swagger;

public class User {

	    private String name;
	    private Integer age;

		public String getName() {
	        return name;
	    }
	 
	    public void setName(String name) {
	        this.name = name;
	    }
	 
	    public Integer getAge() {
	        return age;
	    }
	 
	    public void setAge(Integer age) {
	        this.age = age;
	    }
}

package cn.lijunkui.springbootlearn.swagger;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.*;
@RestController()
@RequestMapping("/user")
public class UserController {
    Logger log = LoggerFactory.getLogger(UserController.class);
    /**
     * 根据用户id 查询用户
     * @return
     */
    @GetMapping("/{id}")
    public User get(@PathVariable(name = "id") Long id){
        User user = new User();
        user.setName("lijunkui");
        user.setAge(18);
        log.info("springboot查询用户成功："+"id:{}",id);
        return user;
    }
    /**
     * 添加用户
     */
    @PostMapping()
    public void add(User user){
        log.info("springboot添加用户成功："+"name:{},age:{}",user.getName(),user.getAge());
    }

    /**
     * 全部更新
     * @param user
     */
    @PutMapping()
    public void updatePut(User user){
        log.info("springboot Put 修改用户成功："+"name:{},age:{}",user.getName(),user.getAge());
    }
    /**
     * 局部更新
     */
    public void updatePatch(@PathVariable("name") String name){
        log.info("springboot Patch 修改用户成功："+"name:{}",name);
    }
    /**
     * 删除用户
     */
    @DeleteMapping("/{id}")
    public void delete(@PathVariable("id") Long id){
        User user = new User();
        user.setName("lijunkui");
        user.setAge(18);
        log.info("springboot 删除用户成功："+"id:{}",id);
    }

    /**
     * 根据requestBody 更新用户信息
     * @param user
     * @return
     */
    @PostMapping("/updateUserByRequestBody")
    public void updateUserByRequestBody(@RequestBody User user){
        log.info("updateUserByRequestBody 修改用户成功："+"name:{},age:{}",user.getName(),user.getAge());
    }
}

编写swagger Config 使用 swagger

package cn.lijunkui.springbootlearn.swagger;

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
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;
//让Spring来加载该类配置
@Configuration
//是否禁用swagger 的配置
@ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true")
//启用Swagger2
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket alipayApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("简单用户管理API接口文档")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ljk.springBootLearn.users"))
                .paths(PathSelectors.any()).build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SprignBoot学习专栏")
                .description("集成swagger")
                .termsOfServiceUrl("https://blog.csdn.net/ljk126wy")
                //创建人
                .contact(new Contact("桌前明月", "http://www.baidu.com", ""))
                //版本
                .version("1.0")
                //API 描述
                .description("简单介绍如有问题还望指正")//
                .build();
    }
}

application.yml 配置内容

server:
  port: 8080 #游览器访问项目端口号
  servlet:
    context-path: /springootLearn #游览器访问项目的名称
swagger:
  enable: true

添加用户

我们可以添加用户进行测试

我们这里就不一个个进行测试啦。

接下来我们开始对每个接口进行接口描述介绍

package cn.lijunkui.springbootlearn.swagger;
import io.swagger.annotations.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.*;
@Api(tags ="用户管理")
@RestController()
@RequestMapping("/user")
public class UserController {
    Logger log = LoggerFactory.getLogger(UserController.class);
    /**
     * 根据用户id 查询用户
     * @return
     */
    @ApiOperation(value="根据id获取用户信息")
    @ApiImplicitParam(paramType= "path", name = "id", value = "用户id", required = true, dataType = "Long")
    @GetMapping("/{id}")
    @ApiResponses({ @ApiResponse(code = 400, message = "请求无效 (Bad request)") })
    public User get(@PathVariable(name = "id") Long id){
        User user = new User();
        user.setName("lijunkui");
        user.setAge(18);
        log.info("springboot查询用户成功："+"id:{}",id);
        return user;
    }
    /**
     * 添加用户
     */
    @ApiOperation(value="添加用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name="name",value="用户名",dataType="string", required = true, paramType = "form",example="ljk"),
            @ApiImplicitParam(name="age",value="用户年龄",dataType="int", paramType = "form")})
    @PostMapping()
    public void add(User user){
        log.info("springboot添加用户成功："+"name:{},age:{}",user.getName(),user.getAge());
    }

    /**
     * 全部更新
     * @param user
     */
    @PutMapping()
    public void updatePut(User user){
        log.info("springboot Put 修改用户成功："+"name:{},age:{}",user.getName(),user.getAge());
    }
    /**
     * 局部更新
     */
    public void updatePatch(@PathVariable("name") String name){
        log.info("springboot Patch 修改用户成功："+"name:{}",name);
    }
    /**
     * 删除用户
     */
    @DeleteMapping("/{id}")
    public void delete(@PathVariable("id") Long id){
        User user = new User();
        user.setName("lijunkui");
        user.setAge(18);
        log.info("springboot 删除用户成功："+"id:{}",id);
    }

    /**
     * 根据requestBody 更新用户信息
     * @param user
     * @return
     */
    @PostMapping("/updateUserByRequestBody")
    public void updateUserByRequestBody(@RequestBody User user){
        log.info("updateUserByRequestBody 修改用户成功："+"name:{},age:{}",user.getName(),user.getAge());
    }
}

@Api ：说明接口类的作用。

@ApiOperation 用在方法上说明方法的作用 @ApiImplicitParam 方法中参数的说明 paramType head 请求参数获取 @RequestHeader query 请求参数获取 @RequestParam path 请求参数获取 @PathVariable body form name 参数名 value 参数的意思 required 参数是否必传 dataType 参数类型 defaultValue 默认值

@ApiImplicitParams：添加多个方法中参数的说明包含 @ApiImplicitParam

@ApiModel:描述model信息

@ApiModelProperty:描述model属性的信息

@ApiModel(value="user对象",description="用户对象user")
public class User {
	    @ApiModelProperty(value="用户名",name="name",example="xingguo")
	    private String name;
	    @ApiModelProperty(value="年龄1",name="age",required=true)
	    private Integer age;

		public String getName() {
	        return name;
	    }
	 
	    public void setName(String name) {
	        this.name = name;
	    }
	 
	    public Integer getAge() {
	        return age;
	    }
	 
	    public void setAge(Integer age) {
	        this.age = age;
	    }
}

@ApiResponses @ApiResponse 错误相应信息描述

参考文献：https://yq.aliyun.com/articles/181435

springboot2.0 快速学习集成swagger

猜你喜欢