在SpringBoot项目中的使用Swagger的方法示例

@Api：放在 请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。
tags="说明该类的作用"
value="描述该类作用" [推荐用这个]

@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 ，将在文档中隐藏

@ApiOperation："用在请求的方法上，说明方法的作用"
	  value="说明方法的作用"
	  notes="方法的备注说明"

@Api(tags="用户模块")
@Controller
public class UserController {

	@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);
	}
}

@ApiResponses：方法返回对象的说明
	@ApiResponse：每个参数的说明
	    code：数字，例如400
	    message：信息，例如"请求参数没填好"
	    response：抛出异常的类

@ApiModel：用于JavaBean的类上面，表示此 JavaBean 整体的信息
			（这种一般用在post创建的时候，使用 @RequestBody 这样的场景，
			请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 ）

@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 略*/
}

   io.springfox
   springfox-swagger2
   2.2.2


   io.springfox
   springfox-swagger-ui
   2.2.2

package com.zhiyou100.configBeans;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @Author ZhengZiXuan
 * @Desc
 */
@Configuration // @Configuration注解，让Spring来加载该类配置。
@EnableSwagger2 //@EnableSwagger2注解来启用Swagger2
public class SwaggerConfigBean {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zhiyou100.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("使用Swagger2 构建RESTful APIS - 废物")
                .description("废物 - Swagger使用演示")
                .termsOfServiceUrl("www.zzxBIuBIuBIu.com")
                .version("1.0")
                .build();
    }

}

package com.zhiyou100.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;

/**
 * @Author ZhengZiXuan
 * @Desc
 */
@Controller
@Api("测试Swagger 的Controller类")
public class TestController {
    @ApiOperation(value="根据id查询名字",notes = "备注:无")
    @ApiImplicitParam(name = "id",value = "用户id",required = true,
            paramType = "query",dataType = "Integer")
    @RequestMapping("/getNameById")
    @ResponseBody
    public String getNameById(int id){
        return "张三";
    }
}

package com.zhiyou100.model;

/**
 * @Author ZhengZiXuan
 * @Date 2021/05/10
 * @Desc
 */

public class User {

    private int id;
    private String name;
    private String password;

    @Override
    public String toString() {
        return "User{" +
                "id=" + id +
                ", name='" + name + '\'' +
                ", password='" + password + '\'' +
                '}';
    }

    public User() {
    }

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

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

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public User(int id, String name, String password) {
        this.id = id;
        this.name = name;
        this.password = password;
    }
}

package com.zhiyou100.controller;

import com.zhiyou100.model.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

/**
 * @Author ZhengZiXuan
 * @Date 2021/05/10
 * @Desc  
有点BUG  就是list集合中的增删改
 */
@RestController
@Api("User类的增删改查API")
public class UserController {
    ArrayList users = null;
    public UserController(){
        users = new ArrayList<>();
        users.add(new User(1,"张三","123"));
        users.add(new User(2,"李四","1234"));
        users.add(new User(3,"王五","12345"));
        System.out.println("init users "+users);
    }
    /**
     * 根据id查User
     */
    @ApiOperation("根据id查用户")
    @ApiImplicitParam(name = "id",value = "用户id",
                      required = true,paramType = "path",
                        dataType = "Integer")
    @RequestMapping(value="/user/get/{id}",method = RequestMethod.GET)
    public User getUserById(@PathVariable("id") Integer id){
        System.out.println("getUserById id: "+id);
        if (id != null){
            if (id>0 && id <4){
                User user = users.get(id);
                System.out.println("getUserById User: "+user);
                return user;
            }
        }
        return null;
    }
    /**
     * 查全部user
     */
    @ApiOperation("查询全部用户")
    @RequestMapping(value="/user/get",method = RequestMethod.GET)
    public List getAllUser(){
        System.out.println("getAllUser");
        return users;
    }

    /**
     * 添加User
     */
    @ApiOperation("添加用户")
    @ApiImplicitParam(name="user",value = "用户对象",paramType = "body",dataType = "User")
    @RequestMapping(value="/user/add",method = RequestMethod.POST)
    public User addUser(@RequestBody User user){
        System.out.println("addUser User:"+user);
        if (user == null || user.getId() == 0){
            return null;
        }
        users.add(user);
        return user;
    }

    /**
     * 删除User
     */
    @ApiOperation("根据id删除用户")
    @ApiImplicitParam(name = "id",value = "用户id",
            required = true,paramType = "path",
            dataType = "Integer")
    @RequestMapping(value="/user/delete/{id}",method = RequestMethod.DELETE)
    public boolean delUserById(@PathVariable("id") Integer id){
        System.out.println("delUserById id:"+id);
        if (id != null){
            users.remove(id);
            return true;
        }
        return false;
    }

    /**
     * 更新User
     */
    @ApiOperation("根据id更新用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "用户id",
                    required = true,paramType = "path",
                    dataType = "Integer"),
            @ApiImplicitParam(name = "user",value = "用户对象",
                    required = true,paramType = "body",
                    dataType = "User")})
    @RequestMapping(value="/user/update/{id}",method = RequestMethod.PUT)
    public boolean UpdateUserById(@PathVariable("id") Integer id,@RequestBody User user){
        System.out.println("UpdateUserById id:"+id+"  ,   User:"+user);
        if (id != null && user != null){
            users.add(id,user);
            return true;
        }
        return false;
    }

}