springboot配置swagger-rest文檔

前言

swagger是一個很好的restful形式的api文檔，可以通過比較小的侵入來提供很好的restful的文檔。因為swagger是依賴服務生成的，是以其實是依賴服務的，這也算是它的一個小缺點吧。但是其實如果一個項目習慣去手寫文檔之後，也是可以的，但是新的項目還是建議去用一些自動生成的文檔，省去了很多麻煩。

spring boot配置swagger

引入swagger依賴

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

編寫swagger對應的配置

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

@Configuration

@EnableSwagger2

public class SwaggerConfig {

       
@<span class="hljs-type">Bean</span>
<span class="hljs-keyword">public</span> <span class="hljs-type">Docket</span> createRestApi() {
                <span class="hljs-comment">// 文檔類型</span>
    <span class="hljs-keyword">return</span> new <span class="hljs-type">Docket</span>(<span class="hljs-type">DocumentationType</span>.<span class="hljs-type">SWAGGER_2</span>)
            <span class="hljs-comment">// 建立api的基本資訊</span>
            .apiInfo(apiInfo())
            <span class="hljs-comment">// 選擇哪些接口去暴露</span>
            .select()
            <span class="hljs-comment">// 掃描的包</span>
            .apis(<span class="hljs-type">RequestHandlerSelectors</span>.basePackage(<span class="hljs-string">"com.demo.web.controller"</span>))
            .paths(<span class="hljs-type">PathSelectors</span>.any())
            .build();
}

<span class="hljs-keyword">private</span> <span class="hljs-type">ApiInfo</span> apiInfo() {
    <span class="hljs-keyword">return</span> new <span class="hljs-type">ApiInfoBuilder</span>()
            .title(<span class="hljs-string">"groundhog-web swagger文檔"</span>)
            .contact(<span class="hljs-string">"name"</span>)
            .version(<span class="hljs-string">"1.0"</span>)
            .build();
}
           
        


}

           

在api和請求參數中使用注解

接口中使用swagger注解

@RestController
@Api(value = "測試swagger", description = "測試swagger api")
public class TestSwaggerController {
       
<span class="hljs-variable">@ApiOperation</span>(value = <span class="hljs-string">"傳回url中的參數"</span>, notes = <span class="hljs-string">"傳回url中的參數"</span>)
<span class="hljs-variable">@ApiImplicitParam</span>(name = <span class="hljs-string">"id"</span>, value = <span class="hljs-string">"id值"</span>, paramType = <span class="hljs-string">"path"</span>, required = true, dataType = <span class="hljs-string">"Integer"</span>)
<span class="hljs-variable">@GetMapping</span>(path = <span class="hljs-string">"/getUrlParam/{id}"</span>)
public Integer getUrlParam(<span class="hljs-variable">@PathVariable</span>(value = <span class="hljs-string">"id"</span>) Integer id) {
    <span class="hljs-selector-tag">return</span> <span class="hljs-selector-tag">id</span>;
}
           
        


}

           

可以通路localhost:port/swagger-ui.html看到生成的swagger文檔。可以看到請求結果：

也可以看到之前post方法的接口也可以生成對于的參數文檔，這裡也可以對表單參數bean使用@ApiModel和@ApiProperty注解進行辨別。

swagger相關注解和官方文檔

swagger常用注解：

1. @Api：修飾整個類，描述controller的作用
2. @ApiOperation：描述一個類的一個方法，或者說一個接口
3. @ApiParam：單個參數描述
4. @ApiModel：用對象來接收參數
5. @ApiProperty：用對象接收參數時，描述對象的一個字段
6. @ApiImplicitParam：一個請求參數
7. @ApiImplicitParams：多個請求參數

這裡推薦下官方文檔，感興趣可以看一下其他注解和相關配置：

[注解官方文檔](

原文位址：https://blog.csdn.net/zlj1217/article/details/82829891                 </div>