springboot,swagger2

1.  添加jar包依赖

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

2. 配置文件放config文件夹下

@Configuration@EnableSwagger2public class Swagger2 { 
    
　　//环境配置进行设置  
　　@Value(value="${swagger.enabled}")    
　　Boolean swaggerEnabled;   
     
　　@Bean    
　　public Docket createRestApi() {        
　　　　return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())               
　　　　 //是否开启swagger，正式环境一般是需要关闭的，可根据springboot的多环境配置进行设置                
　　　　.enable(swaggerEnabled).select()                
　　　　//扫描的包路径                
　　　　.apis(RequestHandlerSelectors.basePackage("com.dzt"))                
　　　　.paths(PathSelectors.any()).build();    
　　}    
　　private ApiInfo apiInfo() {        
　　　　return new ApiInfoBuilder()                
　　　　.title("SpringBoot 构建Swagger2 展示Restful-Api")                
　　　　.description("描述信息")                
　　　　.termsOfServiceUrl("https://www.cnblogs.com/dztHome/")                
　　　　//作者信息                
　　　　.contact("dzt")                
　　　　.version("1.0")                
　　　　.build();    
　　}       
 }

3.接口添加注释

@RestController
public class UserController {

    // 创建线程安全的Map
    static Map<Integer, User> users = Collections.synchronizedMap(new HashMap<Integer, User>());

    /**
     * 根据ID查询用户
     * @param id
     * @return
     */

　　　　//设置该接口名称，详情

　　 @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
　　　//设置传入参数名称，详情，是否必须，类型等
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
    @RequestMapping(value = "user", method = RequestMethod.GET)
    public ResponseEntity<JsonResult> getUserById ( Integer id){
        JsonResult r = new JsonResult();
        try {
            User user = users.get(id);
            r.setResult(user);
            r.setStatus("ok");
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus("error");
            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }

    /**
     * 查询用户列表
     * @return
     */
    @ApiOperation(value="获取用户列表", notes="获取用户列表")
    @RequestMapping(value = "users", method = RequestMethod.GET)
    public ResponseEntity<JsonResult> getUserList (){
        JsonResult r = new JsonResult();
        try {
            List<User> userList = new ArrayList<User>(users.values());
            r.setResult(userList);
            r.setStatus("ok");
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus("error");
            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }

    /**
     * 添加用户
     * @param user
     * @return
     */
    @ApiOperation(value="创建用户", notes="根据User对象创建用户")
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    @RequestMapping(value = "user", method = RequestMethod.POST)
    public ResponseEntity<JsonResult> add (@RequestBody User user){
        JsonResult r = new JsonResult();
        try {
            users.put(user.getId(), user);
            r.setResult(user.getId());
            r.setStatus("ok");
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus("error");

            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }

    /**
     * 根据id删除用户
     * @param id
     * @return
     */
    @ApiOperation(value="删除用户", notes="根据url的id来指定删除用户")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
    @RequestMapping(value = "user/{id}", method = RequestMethod.DELETE)
    public ResponseEntity<JsonResult> delete (@PathVariable(value = "id") Integer id){
        JsonResult r = new JsonResult();
        try {
            users.remove(id);
            r.setResult(id);
            r.setStatus("ok");
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus("error");

            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }

    /**
     * 根据id修改用户信息
     * @param user
     * @return
     */
    @ApiOperation(value="更新信息", notes="根据url的id来指定更新用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long",paramType = "path"),
            @ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
    })
    @RequestMapping(value = "user/{id}", method = RequestMethod.PUT)
    public ResponseEntity<JsonResult> update (@PathVariable("id") Integer id, @RequestBody User user){
        JsonResult r = new JsonResult();
        try {
            User u = users.get(id);
            u.setUsername(user.getUsername());
            u.setAge(user.getAge());
            users.put(id, u);
            r.setResult(u);
            r.setStatus("ok");
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus("error");

            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }

    @ApiIgnore//使用该注解忽略这个API
    @RequestMapping(value = "/hi", method = RequestMethod.GET)
    public String  jsonTest() {
        return "Hello Word!";
    }
}

4. 访问网址：localhost:8080/swagger-ui.html

5.注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

关于参数的详细解释(paramType取不恰当的值会影响后台接受参数)

属性                 取值             作用
paramType                　　　　 查询参数类型
             path                以地址的形式提交数据
             query       　　　　 直接跟参数完成自动映射赋值
             body                以流的形式提交 仅支持POST
             header      　　　　 参数在request headers 里边提交
             form                以form表单的形式提交 仅支持POST

dataType                  　　　  参数的数据类型 只作为标志说明，并没有实际验证
             Long     
             String     

name                　　　　　　　　接收参数名（必须与方法中参数名一致）

value                 　　　　　　　接收参数的意义描述（描述信息）

required              　　　　　　 参数是否必填
             true      　　　　　　必填
             false     　　　　   非必填

defaultValue        　　　　　　　　默认值