springboot整合swagger接口文档

最新推荐文章于 2025-09-10 09:37:09 发布

原创最新推荐文章于 2025-09-10 09:37:09 发布 · 158 阅读

0 ·

CC 4.0 BY-SA版权

springboot学习专栏收录该内容

5 篇文章

订阅专栏

本文档介绍了如何在SpringBoot项目中集成Swagger，用于快速生成接口文档。内容包括引入相关依赖，配置Swagger，创建Controller并注解，以及如何访问生成的Swagger UI。示例中展示了BookController的创建和API定义，如创建、修改、删除和获取图书的接口。最后提到了可以通过Shiro或Spring Security进行接口权限配置，并提供了官方文档链接和项目源码地址。

swagger简介：用以编写接口文档，比起传统手动写接口文档更便捷，直观，通过swagger提供的api注解，可自定义配置接口和参数并加以描述。

1、引用依赖

引用swagger的依赖：

（1）springfox-swagger2 是核心依赖。

（2）springfox-swagger-ui 是提供swagger的文档页面的依赖，可通过 /swagger-ui.html来访问。

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

2、swagger配置

下面两个方法使用到了建造者模式，用于配置swagger。

（1）apiInfo() 是配置swagger-ui.html的页面。

（2）createRestApi()以bean的方式注入到springboot中，其中配置中需要扫描配置控制层（接口）的包，我这里是 com.shiyouao.swagger.controller。

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.shiyouao.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restfun风格，https://blog.youkuaiyun.com/master_02")
                .termsOfServiceUrl("https://blog.youkuaiyun.com/master_02")
                .version("1.0")
                .build();
    }
}

3、创建controller并配置swagger api

3.1 Swagger使用的注解及其说明：

 @Api ：用在类上，说明该类的作用。

 @ApiOperation ：注解来给API增加方法说明。

 @ApiResponses ：用于表示一组响应

 @ApiResponse ：用在@ApiResponses中，一般用于表达一个错误的响应信息 
    code：数字，例如400 
    message：信息，例如"请求参数没填好" 
    response：抛出异常的类 

 @ApiModel ：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候） 

 @ApiModelProperty ：描述一个model的属性

 @ApiImplicitParams : 用在方法上包含一组参数说明。

 @ApiImplicitParam ：用来注解来给方法入参增加说明。
 注意：@ApiImplicitParam的参数说明：
   paramType：指定参数放在哪个地方
   header：请求参数放置于Request Header，使用@RequestHeader获取
   query：请求参数放置于请求地址，使用@RequestParam获取
   path：（用于restful接口）-->请求参数的获取：@PathVariable
   body：（不常用）
   form（不常用） 
   name：参数名
   dataType：参数类型
   equired：参数是否必须传 true | false
   value：说明参数的意思
   defaultValue：参数的默认值

3.2 示例 BookController接口说明：

用户创建某本图书 POST /books/

用户修改对某本图书 PUT /books/:id/

用户删除对某本图书 DELETE /books/:id/

用户获取所有的图书 GET /books

用户获取某一图书 GET /Books/:id

@RestController
@RequestMapping(value = "/books")
public class BookController {

    Map<Long, Book> books = Collections.synchronizedMap(new HashMap<Long, Book>());

    /**
     * Conntroller中定义的方法必须在@RequestMapper中显示的指定RequestMethod类型，
     * 否则SawggerUi会默认为全类型皆可访问， API列表中会生成多条项目。
     * @return
     */
    @ApiOperation(value="获取图书列表", notes="获取图书列表")
    @RequestMapping(value={"/getBook"}, method= RequestMethod.GET)
    public List<Book> getBook() {
        List<Book> book = new ArrayList<>(books.values());
        return book;
    }

    /**
     *
     * @param book
     * @return
     */
    @ApiOperation(value="创建图书", notes="创建图书")
    @ApiImplicitParam(name = "book", value = "图书详细实体", required = true, dataType = "Book")
    @RequestMapping(value="", method=RequestMethod.POST)
    public String postBook(@RequestBody Book book) {
        books.put(book.getId(), book);
        return "success";
    }

    /**
     * paramType会直接影响程序的运行期，如果paramType与方法参数获取使用的注解不一致，会直接影响到参数的接收。
     * @param id
     * @return
     */
    @ApiOperation(value="获图书细信息", notes="根据url的id来获取详细信息")
    @ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Long",paramType = "path")
    @RequestMapping(value="/{id}", method=RequestMethod.GET)
    public Book getBook(@PathVariable Long id) {
        return books.get(id);
    }

    @ApiOperation(value="更新信息", notes="根据url的id来指定更新图书信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "图书ID", required = true, dataType = "Long",paramType = "path"),
            @ApiImplicitParam(name = "book", value = "图书实体book", required = true, dataType = "Book")
    })
    @RequestMapping(value="/{id}", method= RequestMethod.PUT)
    public String putUser(@PathVariable Long id, @RequestBody Book book) {
        Book book1 = books.get(id);
        book1.setName(book.getName());
        book1.setPrice(book.getPrice());
        books.put(id, book1);
        return "success";
    }
    @ApiOperation(value="删除图书", notes="根据url的id来指定删除图书")
    @ApiImplicitParam(name = "id", value = "图书ID", required = true, dataType = "Long",paramType = "path")
    @RequestMapping(value="/{id}", method=RequestMethod.DELETE)
    public String deleteUser(@PathVariable Long id) {
        books.remove(id);
        return "success";
    }

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