SpringBoot基础教程(九) | Swagger篇

Swagger介绍

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTFUL风格的web服务。目标是使客户端和文件系统作为服务器一同样的速度来更新文件的方法，参数和模型紧密集成到服务器。这个解释简单点来讲就是说，swagger是一款可以根据RESTFUL风格生成的接口开发文档，并且支持做测试的一款中间软件。

• 优点：

  • 不用再手写Wiki接口拼大量参数，避免手写错误
  • 对代码侵入性低，采用全注解的方式，开发简单
  • 方法参数名修改、新增、减少参数都可以直接生效，不用手动维护

• 缺点：

  • 增加了开发成本，写接口还得再写一套参数配置

引入Maven依赖

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

编写Swagger2配置

/**
 * Swagger2配置
 */
@Configuration
public class Swagger2Conf {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("training.springboot.cache"))//这里配置swagger扫描的base包
                .paths(PathSelectors.any())//筛选路径
                .build();
    }

    private ApiInfo apiInfo() {
        ApiInfo build = new ApiInfoBuilder()
                .title("SpringBoot 整合 swagger2 练习")
                .description("Swagger2页面的描述")
                .termsOfServiceUrl("")
                .contact(new Contact("youzhihua","https://blog.nowcoder.net/youzhihua","1761595830@qq.com"))
                .version("1.0.0")
                .build();
        return build;
    }

}

使用Swagger注解

/**
 * 书籍实体类
 */
@Table(name = "book")
@ApiModel("书籍实体")
public class Book implements Serializable {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @ApiModelProperty("书籍编号")
    private Integer id;
    @ApiModelProperty("书籍名称")
    private String bookName;
    @ApiModelProperty("书籍作者")
    private String bookAuthor;

    public Book() {
    }

    public Integer getId() {
        return id;
    }

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

    public String getBookName() {
        return bookName;
    }

    public void setBookName(String bookName) {
        this.bookName = bookName;
    }

    public String getBookAuthor() {
        return bookAuthor;
    }

    public void setBookAuthor(String bookAuthor) {
        this.bookAuthor = bookAuthor;
    }
}

@RestController
@Api(tags = "1.0.0", value = "书籍控制器")
public class BookController {

    @Autowired
    private BookService bookService;

    //获取所有书的信息
    @RequestMapping(value = "/queryAllBookInfo",method = RequestMethod.GET)
    @ApiResponse(message = "查询所有书籍信息",code = 200)
    public List<Book> queryAllBookInfo(){
        return bookService.queryAllBookInfo();
    }

    //根据主键获取书的信息
    @RequestMapping(value = "/queryBookById",method = RequestMethod.GET)
    @ApiImplicitParam(value = "书籍Id")
    @ApiResponse(message = "根据书籍Id查询书籍信息",code = 200)
    public Book queryBookById(Integer id){
        return bookService.queryBookById(id);
    }

    //更新书的信息
    @RequestMapping(value = "/updateBookInfo",method = RequestMethod.POST)
    @ApiImplicitParam(value = "书籍对象实体")
    public Book updateBookInfo(Book book){
        return bookService.updateBookInfo(book);
    }

    //删除书的信息
    @RequestMapping(value = "/deleteBookInfo",method = RequestMethod.DELETE)
    @ApiImplicitParam(value = "书籍Id")
    @ApiResponse(message = "删除书籍的个数",code = 200)
    public Integer deleteBookInfo(Integer id){
        return bookService.deleteBookInfo(id);
    }

    //增加一本书的信息
    @RequestMapping(value = "/insertBook",method = RequestMethod.POST)
    @ApiImplicitParam(value = "书籍对象实体")
    public Book insertBook(Book book){
        return bookService.insertBook(book);
    }

}

• Swagger2常用注解

1.Api：Api 用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源。
2.ApiModel：用于描述一个实体的信息，一般修饰在POJO类名上。
3.ApiModelProperty：用于描述一个实体的信息，一般修饰在POJO的属性上。
4.ApiImplicitParam：描述方法的输入参数。
5.ApiResponse：描述方法的响应参数。
6.ResponseHeader：描述方法的响应头部。

测试

启动项目后，输入http://localhost:8080/swagger-ui.html便可以进入到Swagger界面。