SpringBoot项目在线生成API文档

0.安装Lombok插件,Lombok是一个主要用来消除POJO模板式代码的框架．

IDE安装Lomok插件，在setting>plugins的marketplace中搜索Lombok,找到lombok plugin点击安装即可

 

1.搭建项目框架

2.SpringBoot集成Swagger

    2.1　引入两个Swagger的两个依赖(Springfox-swagger2和Springfox-swagger-ui)和Lombok的依赖

pom.xml文件

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.springbootdemo</groupId>
    <artifactId>firstboot</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>firstboot</name>
    <description>Demo project for Spring Boot</description>

    <properties>
        <java.version>1.8</java.version>
    </properties>


    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.5.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <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>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.16.8</version>
        </dependency>

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

2.2创建主类Application,在该类中除了启动springboot的@SpringBootApplication注解外,还添加了@EnableSwagger2注解来启动Swagger

package com.mytest.firstboot;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class,args);
    }
}

2.3为看到Swagger的各种使用方式,在这创建模型类User

package com.mytest.firstboot.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Getter;

@ApiModel(" 用户模型")
@AllArgsConstructor
@Getter
public class User {
    @ApiModelProperty("用户ID")
    private int id;
    @ApiModelProperty("用户姓名")
    private String name;
    @ApiModelProperty("用户密码")
    private String password;

}

 

在模型中,使用了4个注解

@Getter:是一个Lombok注解,用来为POJO类生产getter方法,免除我们自己手动生成;

@AllArgsConstructor:是一个Lombok注解,,用来为POJO类生成全参构造器;

@ApiModel:是一个Swagger注解,用来为POJO类做注释;

@ApiModelProperty:是一个Swagger注解,用来为POJO类的属性做注释。

2.4创建一个简单的Controller

package com.mytest.firstboot.controller;

import com.mytest.firstboot.model.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@Api("user相关api")
@RestController
@RequestMapping("/user")
public class FirstBootUserController {
    @ApiOperation("根据id获取用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query",name="id",dataType = "int",required = true,value="用户的id",defaultValue = "1")
    })
    @ApiResponses({
            @ApiResponse(code=400,message="请求参数没填好"),
            @ApiResponse(code=404,message="请求路径没有或者页面跳转路径错误")
    })
    @RequestMapping(value="/getUserInfo",method= RequestMethod.GET)
    public User getUserInfo(@RequestParam("id")int id){
        if(id==1){
            return new User(1,"小红","123456");
        }
        return new User(2,"小刚","123456");
    }
}

在该Controller中提供了一个简单的根据Id获取User信息的接口，该类除了使用Spring的注解外，还使用了6个Swagger注解

@Api：通常用来为Controller类做注释，说明Controller的职能；

@ApiOperation:通常用来为一个接口做注释,说明接口的职能;

@ApiImplicitParams:通常用来包含接口的一组参数注解,可以简单的理解为参数注解的集合;

@ApiImplicitParam:用来在@ApiImplicitParams注解用,说明一个请求参数的各方面该注解包含一下几个常用选项,

>>>>@paramType,参数放置的地方,包含query、header、path、body、form，最常用的是前4个。需要注意的是，query域中的值需要使用@RequestParam获取；header域中的值需要使用@RequestHeader获取；path域中的值需要使用@PathVariable获取；body域中的值需要使用@RequestBody获取;否则就可能出错。

>>>>@name,参数名

>>>>@dataType,参数类型

>>>>@required,参数是否必传

>>>>@value,参数的值

>>>>@defaultValue,参数默认值

@ApiResponses:用来包含接口一组响应注解,可以简单理解为响应注解的集合;

@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息;

>>>>code,即httpCode数字,例如400,404等

>>>>message,信息,例如"请求参数没有填好"

以上注解就是开发中最常用的Swagger注解,到此SpringBoot与Swagger集成完成.

3 生成Swagger文档

首先启动firstboot项目后,在浏览器中输入http://localhost:8080/swagger-ui.html,

3.1Swagger文档分析

生成文档,获取到如下图页面

项目中的各个注解在上图中都有体现

3.2使用Swagger文档进行接口调用

在想要运行的方法中填好入参后,单击"Try it out!"按钮,便可执行该接口

执行结果如图