swagger2-实时生成接口文档

1.swagger 简介

网址：swagger.
Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

2.swagger 入门程序

1. 使用Swagger注解





2. 使用示例

1.引用依赖

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

2.文档配置对象

import io.swagger.annotations.Api;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@Configuration//spring 配置文件（代替xml、bean）
@EnableSwagger2//开启配置文档
public class SwaggerConfig {

//    配置文档属性
    private ApiInfo apiInfo(){
//      api文档属性构建对象
       return new ApiInfoBuilder()
                .title("用户接口开发文档")
                .description("这是开发者文档")
                .termsOfServiceUrl("http://www.ujiuye.com")
                .version("1.0")
                .build();
    }
//    ****创建bean 配置对象****
    @Bean
    public Docket getDocket(){
       return  new Docket(DocumentationType.SWAGGER_2) //配置对象版本号
                .groupName("开发组")//组名
                .apiInfo(apiInfo())//文档属性
                .select()//选择当前项目下  带文档注解  的全部生成文档
                .build();
    }


}

3.swagger文档注解

model代码

package com.offcn.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@AllArgsConstructor
@NoArgsConstructor

//swagger文档注解
@ApiModel(value = "用户实体类")
public class User {
    //swagger文档注解，实体类属性
    @ApiModelProperty(value = "用户的编号")
    private Long id;
    @ApiModelProperty(value = "用户的名字")
    private String name;
    @ApiModelProperty(value = "用户的年龄")
    private Integer age;
}

控制器代码

package com.offcn.controller;

import com.offcn.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

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

@Controller
@ResponseBody
@RequestMapping("/user")

//swagger文档注解
@Api(tags = "用户操作接口类")

public class UserController {
//    模拟数据库

//    Collections.synchronizedList:实现list线程安全代码（加同步代码块）
    private List<User> userList= Collections.synchronizedList(new ArrayList<>());

//   1. 查询用户列表
    @GetMapping("/")
    @ApiOperation("查询用户列表")
    public List<User> findAll(){
        return userList;
    }

//   2. 新增用户
    @PostMapping("/")
//    @RequestBody 表示请求是一个json格式的数据
    //swagger文档注解  @ApiParam接口参数
    @ApiOperation(value = "新增用户方法")
    public String add(@RequestBody @ApiParam(name = "user",value = "用户对象",required = true) User user){
        try {
            userList.add(user);
            return "add-ok";
        } catch (Exception e) {
            e.printStackTrace();
            return "add-fail";
        }
    }

//   3. id查询用户
    @GetMapping("/{id}")
//    @PathVariable(""参数符号)---》用于传递 访问参数
    @ApiOperation("根据id查询用户")
    public User findOne(@PathVariable("id") @ApiParam(name = "id",value = "用户编号",required = true,type = "path") Long id){
        for(User user:userList){
//            longValue:转化为原始数据类型，可以使用双等号
            if(user.getId().longValue()==id.longValue()){
                return user;
            }
        }
        return null;
    }

//  4.  更新用户
    @PutMapping("/{id}")
    @ApiOperation("根据id更新用户")
    @ApiImplicitParam(name = "id",value = "用户编号",required = true,type = "path")
    public String update(@PathVariable("id") Long id,User user){
        try {
            for (User user1:userList){
                if(user1.getId().longValue()==id.longValue()){
                    user1.setName(user.getName());
                    user1.setAge(user.getAge());
                }

            }
            return "upadte--ok";
        } catch (Exception e) {
            e.printStackTrace();
            return "update-fail";
        }
    }

//    5.根据id删除数据
    @DeleteMapping("/{id}")
    @ApiOperation("根据id删除用户")
    @ApiImplicitParam(name = "id",value = "用户编号",required = true,type = "path")
    public String delete(@PathVariable("id") Long id){
        try {
            User user=this.findOne(id);
            userList.remove(user);
            return "delete-ok";
        } catch (Exception e) {
            e.printStackTrace();
            return "delete-fail";
        }
    }
}

3.swagger 调试程序示例

1.访问

2.测试