現(xiàn)在我們的項目中已經(jīng)有了一個可供外部調(diào)用的rest api接口椒舵，隨著項目的擴展以后會有越來越多的接口嫩与，這個時候就需要同時對外部提供關(guān)于接口的詳細(xì)說明文檔，而swagger幫我們使用很少的時間就可以構(gòu)建出一套接口文檔留特。

• 首先在pom.xml中引用swagger所需的依賴堂鲤。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <scope>compile</scope>
 </dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
 </dependency>

• 然后在代碼中開啟swagger

@Configuration
@EnableSwagger2
/** 是否打開swagger **/
//@ConditionalOnExpression("'${swagger.enable}' == 'true'") 可以動態(tài)控制的開關(guān)咙咽，在生產(chǎn)環(huán)境關(guān)閉swagger
public class SwaggerConfig {
    
    
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                 // 掃描controller路徑
                .apis(RequestHandlerSelectors.basePackage("com.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springt boot 從入門到精通 api")
                .description("springt boot 從入門到精通 api")
                .termsOfServiceUrl("http://www.reibang.com/u/c9deb1bda6ce")
                .contact("http://www.reibang.com/u/c9deb1bda6ce")
                .version("1.0.0")
                .build();
    }
    
}

這一步完成之后老玛，啟動項目，打開 localhost:8080/swagger-ui.html#/就可以看到swagger的界面了钧敞，并且我們寫好的那個接口也已經(jīng)躺在那里等我們的調(diào)用蜡豹。
swagger還有更多的注解幫助我們完善接口文檔。

swagger注解

從源碼中可以看到swagger提供了這么多注解溉苛，下面我們將常用的幾個進(jìn)行講解：

@Api：注解在controller上镜廉，可以有以下參數(shù)

    // 接口描述
    String value() value"";
    // 會在swagger頁面顯示兩個標(biāo)簽
    String[] tags() default {""};
    // 是否隱藏
    boolean hidden() default false;

@ApiOperation：注解在接口的方法上

     // 接口描述
    String value();
     // 會在接口上顯示筆記
    String notes() default "";

    String[] tags() default {""};
    // 是否隱藏
    boolean hidden() default false;

@ApiParam：注解在接口參數(shù)上

    // 描述
    String value() default "";
    // 默認(rèn)值
    String defaultValue() default "";
    // 是否必填
     boolean required() default false;
    // 是否隱藏
    boolean hidden() default false;
    // 示例值
    String example() default "";

@ApiModelProperty：注解在model上

    // 描述
     String value() default "";
    // 筆記
    String notes() default "";
    // 是否隱藏
    boolean hidden() default false;
    // 示例參數(shù)
    String example() default "";
    //允許空置
    boolean allowEmptyValue() default false;

您的關(guān)注是我最大的動力