Swagger入門

文檔向來在軟件開發過程中的每一個階段都是非常重要的，如果沒有文檔，那軟件的可維護性就會變得很糟，以致于影響可擴展性，最后慢慢的使軟件變成一堆亂糟糟的無用的代碼。而不同系統之間的接口文檔其重要性更顯而易見，一般常用的接口文檔采用以下形式：

  • [ ] 口口相傳
  • [x] 用world或其他文本文件進行保存
  • [x] 用wiki編寫

上面這些方式都有各自的缺點，比如不易維護，不易測試接口，接口變更而文檔未能同步更新等。但Swagger的出現改變了這些情形，Swagger的文檔編寫相當于就是在寫代碼，在更改接口代碼的同時就能方便的更新文檔，還能方便的進行接口的測試，怎么樣，很心動吧，心動不如行動，那我們開始練習吧。

創建一個Spring boot工程:

Spring boot工程目錄

加入Swagger依賴:

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

寫一個controller作為API接口:

@RestController
@RequestMapping("/demo")
public class DemoController {

    @RequestMapping(value = "/add", method = RequestMethod.POST)
    public User addUser(@RequestBody @Valid User user){
        user.setDescription("had been dealed");
        return user;
    }

    @RequestMapping(value="/delete/{id}", method = RequestMethod.DELETE)
    public ResponseEntity delete(@PathVariable Integer id){
        //mock deleted;
        return new ResponseEntity("User had been deleted", HttpStatus.OK);
    }

    @RequestMapping(value = "/show", method= RequestMethod.GET)
    public User showUser(@RequestParam("id") Integer id){
        User user = new User();
        user.setId(1);
        user.setDescription("show user");
        user.setAge(100);
        user.setUsername("test");
        return user;
    }
}

這個和普通controller沒有撒區別，而我們想要讓它生成出接口文檔，并且能夠供別人進行接口測試，就需要進行Swagger的配置及其相關的注解的幫助了。

配置Swagger

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                //指定要生成api文檔的根包
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                //路徑配置
                .paths(regex("/demo.*"))
                .build()
                .apiInfo(apiInfo());

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger2的Restful API 文檔")
                .description("Spring Boot和Swagger的結合")
                .version("1.0")
                .build();
    }

}

配置好后，就可以啟動你的spring boot 應用，先一睹swagger的芳容，進入這個地址:http://localhost:8000/swagger-ui.html,具體的服務器端口號撒的根據你本地的進行更改，然后就會看到這個頁面:

swagger 頁面

但是，雖然能看到文檔頁面了，但這還比較簡陋，各個Restful方法的具體文檔都還沒有，這些還得靠我們去代碼里加入，畢竟還不是那么智能的，怎么加入呢，請接著往下看。
用@Api在Controller類上定義這個服務的描述信息，像這樣:

@RestController
@RequestMapping("/demo")
@Api(value="demo", description="這是一個Swagger demo的服務")
public class DemoController {
    .....
}

然后在swagger ui里面就看到了對這個controller的描述信息：

@Api in controller class

有注解能對controller進行描述，當然也有注解能對里面的各個方法進行描述，這就是@ApiOperation和它的小伙伴們:


    @RequestMapping(value = "/add", method = RequestMethod.POST,produces = "application/json")
    @ApiOperation(value = "新增一個用戶", response = User.class)
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "成功保存"),
            @ApiResponse(code = 401, message = "你沒權限"),
            @ApiResponse(code = 403, message = "你被禁止訪問了"),
            @ApiResponse(code = 404, message = "沒找到，哈哈哈")
    }
    )
    @ApiImplicitParam(name = "user",
            value = "要新增的用戶",
            dataType = "User",//This can be the class name or a primitive
            required = true,
            paramType = "body")
    public User addUser(@RequestBody @Valid User user){
        user.setDescription("had been dealed");
        return user;
    }

    @RequestMapping(value="/delete/{id}", method = RequestMethod.DELETE,produces = "application/json")
    @ApiOperation(value = "刪除一個用戶", response = ResponseEntity.class)
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "成功保存"),
            @ApiResponse(code = 401, message = "你沒權限"),
            @ApiResponse(code = 403, message = "你被禁止訪問了"),
            @ApiResponse(code = 404, message = "沒找到，哈哈哈")
    }
    )
    @ApiImplicitParam(name="id",
            value = "要刪除的用戶id",
            dataType = "int",//This can be the class name or a primitive
            required = true,
            paramType = "path")//Valid values are {@code path}, {@code query}, {@code body}, {@code header} or {@code form}
    public ResponseEntity delete(@PathVariable Integer id){
        //mock deleted;
        return new ResponseEntity("User had been deleted", HttpStatus.OK);
    }

    @RequestMapping(value = "/show", method= RequestMethod.GET,produces = "application/json")
    @ApiOperation(value = "顯示一個用戶", response = ResponseEntity.class)
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "成功保存"),
            @ApiResponse(code = 401, message = "你沒權限"),
            @ApiResponse(code = 403, message = "你被禁止訪問了"),
            @ApiResponse(code = 404, message = "沒找到，哈哈哈")
    }
    )
    @ApiImplicitParams({
            @ApiImplicitParam(name="id",
                    value = "要刪除的用戶id",
                    dataType = "int",//This can be the class name or a primitive
                    required = true,
                    paramType = "query"),//Valid values are {@code path}, {@code query}, {@code body}, {@code header} or {@code form}
            @ApiImplicitParam(name = "param",
                    value = "其他參數",
                    dataType = "String",//This can be the class name or a primitive
                    required = true,
                    paramType = "query")//Valid values are {@code path}, {@code query}, {@code body}, {@code header} or {@code form}
    })

    public User showUser(@RequestParam("id") Integer id,@RequestParam("param") String otherParam){
        User user = new User();
        user.setId(1);
        user.setDescription("show user");
        user.setAge(100);
        user.setUsername("test");
        return user;
    }

當參數是復雜類型(非原始類或及其包裝類)時,就需要用到@ApiModel和@ApiModelProperty：

@Data
@ApiModel
public class User {
    @ApiModelProperty(notes = "用戶id",required = false,dataType="Integer")
    private Integer id;
    @NotBlank
    @ApiModelProperty(notes = "用戶名",required = true,dataType="String")
    private String username;
    @NotNull
    @Max(100)
    @Min(1)
    @ApiModelProperty(notes = "年齡",required = true,dataType="Integer",allowableValues = "range[0,100]")
    private Integer age;
    @ApiModelProperty(notes = "描述",required = false,dataType="String")
    private String description;
}

注解說明:
@ApiOperation：對方法進行描述，說明方法作用
@ApiResponses：表示一組響應
@ApiImplicitParams：對方法的多個參數進行描述
@ApiImplicitParam：對單個的參數進行描述(name:參數名,value:參數的描述,dataType:參數類型,required:是否必須,paramType:參數來源方式)
@ApiModel：對復雜類型參數進行說明
@ApiModelProperty：對復雜類型字段進行說明

寫了這么多，讓我們看看最終的效果圖吧:

final

這就是最終出來的文檔頁面，那個Try it out!按鈕是用來進行接口測試的，你可以填入參數進行測試。

最后貼上工程代碼:
project code

如果用markdown編寫文章的話，強烈推薦小書匠，真的很好用，這篇文章就是用那個寫出來的?

最后編輯于 ：
?著作權歸作者所有,轉載或內容合作請聯系作者
平臺聲明：文章內容（如有圖片或視頻亦包括在內）由作者上傳并發布，文章內容僅代表作者本人觀點，簡書系信息發布平臺，僅提供信息存儲服務。

推薦閱讀更多精彩內容

  • Spring Boot 參考指南 介紹 轉載自:https://www.gitbook.com/book/qbgb...
    毛宇鵬閱讀 46,958評論 6贊 342
  • Android 自定義View的各種姿勢1 Activity的顯示之ViewRootImpl詳解 Activity...
    passiontim閱讀 173,325評論 25贊 708
  • 你，終會明白 有些人 要等 有些事 很順 有些時候 得熬 等有等的必要 順有順的條件 熬有熬的價值 無論怎樣 都是...
    Mr_Zoul閱讀 271評論 0贊 0
  • 一維空間是直線，二維空間是平面，三維空間是立體，每一維空間都是相對于它的上維空間才能封閉的（上文說過），一維直線是...
    一如當初月閱讀 2,879評論 1贊 0
  • 煙波嫌水瘦！不肯動情深。 捉紋撩秋意，別怨風流人。
    撲忒閱讀 273評論 0贊 3